Wednesday, 5 September 2012

A Comment

Comments in programming languages are hugely useful.  As a programmer, comments are the quickest way to communicate with the reader (who may be yourself at a later moment).  As a beginner comments where really a tool for learning the language, reminding me what that strange syntax, or standard function was supposed to do.  After a while of learning programming from textbooks, I started looking around for different resources, mainly forums.  I got the impression that lots of comments was a great thing.  The result was heavy commenting in the code that followed.

Now I've read "The Practice of Programming" I've finally been able to refresh my way of thinking and look back a little.  It kind of reminded me to think of the purpose of a comment.  A comment should really help the reader along, maybe filling in some technical details of an algorithm or explaining why you've chosen to do an unusual bit fiddle.  It should add something.  Reading old code I've read comments like "// output <some crap> ", and a function "get_foo()" preceded by "// get_foo() gets foo".  This is so clear from the code, it's wasting the readers time being there.  I've moved away from the philosophy that "more comments is better" to "the least comments you can get away with, the better".  And by "get away with", I mean that the code should be completely clear - removing all comments and having cryptic code is definitely much worse to me than too many comments!

Stylistically, my aim has slowly become to write code that is good enough to not need comments.

I'm definitely at a dangerous point in my programming journey.  I feel comfortable with the syntax, the idioms and the quirks (of C/C++).  I understand the value of style, and debugging, and the dangers of things like undefined behaviour.  But it's so easy to become complacent and think you've mastered it.  The reality is, in every area of programming, there is so much more to learn and to improve on.  Hopefully, knowing this I can keep moving in the right direction...

No comments:

Post a Comment