Comments on: Reducing comments and increasing documentation

By: Alex Curylo

Alex Curylo — Tue, 22 Apr 2008 23:49:07 +0000

“without looking at it for 4 or 5 months is just painful.”

Heh. “Months?” Friend, when the OS X transition hit, I had porting projects show up with code I hadn’t seen since I shipped off to the contractors over a DECADE ago. Indeed, one of my current projects right now is to get over to Cocoa a project that has files I haven’t looked at since they were first written in 1998, just shy of that.

The way I put it is,

1) Your first … mmmm … 18 months in the industry you code as cleverly as possible.
2) Then you realize no one cares how clever your code is, including you a couple weeks at most after writing it. So you switch to coding how you figure will actually impress your coworkers/superiors/clients, namely to execute as efficiently as possible.
3) After some time you realize that coding with execution efficiency in mind is a mug’s game since you can rarely guess where the actual time-worthy chokepoints to care about efficiency are.

This is when you attain true enlightenment, and you realize that The Best Code is actually code which is maintainable. That means someone else can take over working on it easily to free you to do more interesting things, plus you can use it yourself easily months/years/decades later. Certainly, I have received many -many- more heartfelt kudos and good recommendations through the years along lines like “Wow!! This is absolutely the EASIEST code to port i have EVER seen!!!” then I ever have for programming I’ve done with any other aim than ‘maintainable’ in mind.

I think there is no next step, and you just refine that epiphany. “Complete unit test coverage” is the next step on my personal path I believe. Well, after “finding a javadoc type system for automatically parsed documentation that honestly isn’t far more trouble than its benefits.”

By: Colin Devroe

Colin Devroe — Mon, 14 Apr 2008 12:51:23 +0000

I find my documentation/commenting style continues to change over time. When my code will be open sourced, I’m much more aware of how I write the comments, typically I just add a simple description with an “accepts” / “returns” type of information.

I would definitely like to find a definitive style… and also find a way to “strip comments” if needed (like in JavaScript).

By: Luke

Luke — Mon, 14 Apr 2008 09:17:59 +0000

Always the best way! But I learnt the hard way too :( my programming style is constantly changing, so not only am I disgusted at my naivety when looking at an old project, I’m also at a loss most of the time to work out what’s going on. Gonna persevere and get this on all my next stuff :)

By: chris rhee

chris rhee — Sat, 12 Apr 2008 15:46:40 +0000

Good call. It would especially be useful if there’s a possibility of handing the code over to someone else in the future.

By: Andy Beeching

Andy Beeching — Sat, 12 Apr 2008 10:20:13 +0000

I quite like this mantra for documentation:

“Comments should contain the word “because”. This way, you know that you are answering a why rather than a what.”

I think it was from this post by Steve Yegge:

http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.html

Anyway, since I write mainly JavaScript atm, I’m using jsDoc to document projects, and try and include a high-level outline of each object at the top of the file explaining it’s purpose. Params and other dependencies are then ‘marked-up’ with the jsdoc syntax.

Inline comments can then still be added if there’s any finicky bit of code.