3 ms·
I, for one, will not accept anyone working for me taking this approach. Code is expensive to produce and it must be well documented for others to maintain, supp
by nkurz 14y ago
I, for one, will not accept anyone working for me taking this approach. Code is expensive to produce and it must be well documented for others to maintain, support and evolve.
You might be right, but you also might be focusing on the wrong thing. There is a case to be made that the goal should be clarity, and comments should be reserved for the cases where the code itself cannot be made clearer. Steve McConnell expresses this particularly well:
http://www.scribd.com/doc/95398523/McConnell-Code-Complete-Chapter-32-Self-Documenting-Code http://www.scribd.com/doc/95398523/McConnell-Code-Complete-C...
The whole chapter is a gem, and it's hard to find a pull-quote that does it justice. It's probably the single piece of writing that most changed my attitude about programming. But if you'd like a starting point, your position sounds a lot like a character in his opening allegory at line 177:
"I want to suggest a commenting standard for our projects," Thrasymachus said. "Some of our programmers barely comment their code, and everyone knows that code without comments is unreadable."
- robomartin 14y agoI didn't have time to read the entire thing. I scanned it quickly and have to say that I don't think I disagree with the recommendations of that paper. In general terms comments should not describe the mechanics of the code "looping through all available names" but rather the intent "Find the user name". That comments get out of sync with code is a fact. That they stay out of sync is inexcusable. What I will generally do is to fully test and debug a chunk of code and then go back and annotate. I sometimes have a "Go comment the code" item in my to-do list and will spend time here and there cleaning-up and clarifying comments. The other interesting thing that can happen when commenting this way is that you can find issues with the code or identify refactoring opportunities. It's like sitting down to explain what the code is doing to another capable programmer as opposes to a 12 year old who is just starting to learn how to program. Maybe that's the best way to put it. What do you say to an experience programmer if you had to do a code review and explain your code? That should go in the comments. If a method or subroutine is absolutely trivial then you say "This finds the average of the voltages across these four inputs". If, on the other hand, the routine is more complex, you have to describe the overall intent "this calculates the values of the missing pixels" and then dive within the module to explain some of the specific techniques being used "Polyphase FIR filter to interpolate image data for missing color samples" or "Bounds-limited adder to clip FIR filter data to legal image data range". In other words, you don't explain every line of code but rather functional chunks that make it easier to navigate it and understand what is being done at a macro level and why. Again, my peeve is with projects that have files upon files with not a single comment. I don't expect a book.
- deleted 14y ago[deleted]