I would argue that the most useful comments don't say what the code does, but rather why it does it. The what you can get from reading the code, but answering why a class exists in the first place, or why particular variables are modified in such a way, it often far less easy to determine.

I agree with David's points about untidy code being a symptom of bigger problems. The article itself I found a depressing read, as I'm currently working on a system which answers a resounding NO to all the questions you raise. Knowing what needs to be done is one thing, getting the business buy-in to change this sorry state of affairs, however, is often only possible when one of the painted-over cracks in the wall causes the house to fall down.

"Good enough" to keep in preference to throwing it away immediately and re-writing from scratch? Yes. (Joel was banging on about this argument back in 2000).

"Good enough" to blissfully hand over the ownership of the project to another team, claiming it's a self-documenting masterpiece? No. The increased maintenance cost likely to be incurred due to a "lack of explicit, consistent technical leadership" (pardon the paraphrasing), coupled with the potential issues highlighted by David in the comment above, would need to be accommodated for.

Perhaps all systems fall between these two extremes. Depending on why you're asking the question of "is it good enough" will veer your opinion towards one or the other. We can all whinge that the code is rubbish, but if the cost of the re-write is coming out of my own pocket, all of a sudden my opinion is likely to be less fatalistic.

So the question is, can an untidy codebase (e.g. messed up structure, layout, etc) be "good enough"?

I think you're right about "why" rather than "what". I tend to comment code rarely and only if I'm writing a complex algo that isn't obvious or where I've had to obfuscate the code for performance or other reasons. I'd put money on the fact that 90%+ of comments are "what" rather than "why" and therefore (IMO) pretty useless :(.

Over commenting or commenting for the sake of it actually makes code worse because it makes it harder to take in a whole routine/class/... on a single page. Enforced coding standards where each method/class needs a header are good examples of where this causes issues.

Perhaps this is self-fullfilling but in my experience teams that do code reviews are rarely the ones that need them.

Putting a "good enough" twist on your question, I'd try to determine how important their answers are to the system that you'll end up with as a result. Is one variant a subset of the others enabling you to go with the more complete approach? Do you need to know the answers now - can you start designing and building without all the answers? Can you work on several approaches?

In the absence of decent requirements you often have to provide your own for the sake of making progress : on time, on budget is a very strong requirement! You may also find that providing your own answers will get a much stronger response (often negative) from those who were supposed to provide them.

Depending on your methodology you may want to highlight the impact of the delay or forego getting answers and try to maintain momentum by getting a prototype in front of someone.

This is always a great question and a nice term to quantify. I have dealt with this often and I find the level of detail I need to go into to find the answer to "good enough?" takes time and plenty of it. Unit tests are the best way as many frameworks (see Emma or for a commercial options Agitar is great) that look at coverage and tests V's outcomes help, especially if you view them over time of the project. If the unit tests per outcome continues to drop you get the feeling that the project started to feel pressure and revert back to bad habits of delivering code without tests. Projects under pressure are generally the ones you need to watch closely (I didn’t say they will always be “not good enough?” but it’s the best ones to review first when time is limited). This only works on projects that have some basic good practices (automated builds, continuous integration). I agree other tools such as checkstyle are also helpful as many tools will report over time how untidy the code has progressively come. What about those projects with none of these available or working? I walked into a project the other day with this exact situation but found a very effective way of quickly assessing if the code was “good enough”. Developer confidence. You can’t measure it with a tool and you have to be able to read different peoples reactions but it works. Tell your developers to imagine they are one day before a release and you need them to change some functionality. Then ask your developers the following questions; 1. How comfortable are you of changing your own code? 2. How comfortable are you of changing your absent team mates code? 3. Finally, pick some complex parts of the system that are critical and ask how comfortable are you of changing that code? The reactions will be mixed but will give you an idea if the developers themselves think the code is good enough. Most developers think their own code is fine (those that don’t will be negative all the way through and take their opinion with a grain of salt). Most developers that are confident in changing their own code will not want to touch anyone else’s if the overall code is “not good enough”. The most interesting part is when people turn white in thinking about changing a complex critical part of the system. Some developers may be positive about all of these but unless all team members are confident then you should look further. Badly written code with little comments (of any kind) and no unit tests scares every developer except those that wrote the code in the first place. As with all behaviors this is subjective but a quick way of prioritising your code reviews (yes I know everyone could lie but you have to trust that most wont). I have used this effectively on many projects now and it has generally worked well. Of course, a bigger study would be interesting.

I've been involved in reviews of all types: Code, design, project plan, requirements, etc. I can tell you they have a very high cost in time, place and not forgetting cookies and coffee.

So, it is a waste of time thinking in a review were an architect is called to spot problems in the comments.

All developers must follow a design, that is actually a detail of the architecture. They have to stick to the best practices, that are actually enforced using an static code analyzer.

Now, we also have a technical lead, whose job it to take care of reviewing the daily decisions the developers make. He is to document any decision that may go against the design.

When the code review is to be done, language experts are summoned to take a look at how the design was implemented in critical spots. (You cannot review the complete code, the analysis tool has done the trivial work for you). They will check if the best ways to implement the solution with the language at hand were used (say, application of idioms).

Then, if the code passes the "well done" mark in terms of language and micro-design decisions, it is the turn of the "what-is-it-doing" review. How good is not only a matter of good language use, it needs to address the result (which is the most important thing), and not the code itself (which is by no means the product).

You then call the designer and/or Architect. Using a visualization tool to view the actual code as classes and relationships, you check were the code takes a different path from the original design. For each one of those variations, there should be a documented reason. That reason is either approved or a recommendation is given to solve the issue in another way. That may require refactoring at any of the three levels (code, design, architecture). Do not forget the smells we can spot when looking at the solution from a higher perspective, like dependencies and such.

Finally, the architect should also have a list of quality attributes the system must achieve. We may check for the specific places where those are actually implemented (a security check, possible performance bottlenecks) and may look at the code there to see if the implementation seems to achieve that quality requirement.

SO, to asnwer when is code good enough? I may say it needs to deliver what is was designed to do, in the way it was designed to do (or at least have a very good rationale of why it is not).

William Martinez