Code Comments & n00bs
Lately, I've found myself pondering and discussing the formatting and commenting of software source code. Steve Yegge made a post on the subject not too long ago, and because he's become frequently cited as a guru, I feel compelled to make a comment or two on the subject.
The post in question demonstrates an alleged difference between the coding and commenting style of inexperienced programmers (n00bs) and experienced programmers. Thing is, in spite of spending over two decades writing software, I can't say I relate particularly well to either case presented, n00b or non-n00b.
Forgiving the n00b example as having a dollop of hyperbole for effect, the experienced case is more interesting to me, because it contains virtually no white space. This isn't the first time I've seen experienced engineers with an aversion to white space. Some coding standards even dictate close placement of braces for the sake squeezing more code on the screen.
Some software creators like their code tightly packed together. Myself, I'm a proponent of white space.
When it comes to published language, the desirability and utility of white space has been well demonstrated--not only by the evolution of the printed word, but in psychological studies as well. Collecting ideas into paragraphs, demarcating blocks of text with white space, titles, subtitles, chapters, headings... It should come as no surprise that these formatting goodies are all fine things that serve important purposes that have stood the test of time. Why do software engineers who eschew whitespace in their code, still use it in their prose?
Programming languages haven't been around nearly as long as publishing, but the use of white space in program code is also encouraged in many computer science classes across the country--as a simple Google search will reveal. The use of white space may not yet be a universally acknowledged good, but the lack of it is hardly an accepted ideal. At best, this is a contentious issue and there are differing schools of thought.
As far as code comments go, the fundamental question in my mind is a question of ROI. Generally, computing problems are solved while you're "in the zone" so to speak. One object of comments in code is to expedite a return to "the zone"--that particular mental state you were in when you wrote the code in the first place. A few well-written comments can save a lot of time towards realizing this end.
It's easy to return befuddled to complex code written a year prior and spend an entire day quizzically wondering what the heck you were thinking--and all the while you'll wish you invested a little more time translating those in the zone thoughts into insightful, useful comments.
When five minutes time from your present self saves your future self a day's work, the ROI is clear (or, if you save some other poor soul's future self a day's work.) At other times, code is so simple and manifestly obvious comments only get in the way as annoying restatements of the obvious.
I see no hard and fast rules on this front. When and how much to comment really boils down to a matter of prudence, but wondering how long it will take you to comprehend the code at hand once you've forgotten it is always a good question to ask--and how much that time might be reduced with a few more comments.
Update: After a little more searching, I found some similar sentiments from Raymond Chen.
The post in question demonstrates an alleged difference between the coding and commenting style of inexperienced programmers (n00bs) and experienced programmers. Thing is, in spite of spending over two decades writing software, I can't say I relate particularly well to either case presented, n00b or non-n00b.
Forgiving the n00b example as having a dollop of hyperbole for effect, the experienced case is more interesting to me, because it contains virtually no white space. This isn't the first time I've seen experienced engineers with an aversion to white space. Some coding standards even dictate close placement of braces for the sake squeezing more code on the screen.
Some software creators like their code tightly packed together. Myself, I'm a proponent of white space.
When it comes to published language, the desirability and utility of white space has been well demonstrated--not only by the evolution of the printed word, but in psychological studies as well. Collecting ideas into paragraphs, demarcating blocks of text with white space, titles, subtitles, chapters, headings... It should come as no surprise that these formatting goodies are all fine things that serve important purposes that have stood the test of time. Why do software engineers who eschew whitespace in their code, still use it in their prose?
Programming languages haven't been around nearly as long as publishing, but the use of white space in program code is also encouraged in many computer science classes across the country--as a simple Google search will reveal. The use of white space may not yet be a universally acknowledged good, but the lack of it is hardly an accepted ideal. At best, this is a contentious issue and there are differing schools of thought.
As far as code comments go, the fundamental question in my mind is a question of ROI. Generally, computing problems are solved while you're "in the zone" so to speak. One object of comments in code is to expedite a return to "the zone"--that particular mental state you were in when you wrote the code in the first place. A few well-written comments can save a lot of time towards realizing this end.
It's easy to return befuddled to complex code written a year prior and spend an entire day quizzically wondering what the heck you were thinking--and all the while you'll wish you invested a little more time translating those in the zone thoughts into insightful, useful comments.
When five minutes time from your present self saves your future self a day's work, the ROI is clear (or, if you save some other poor soul's future self a day's work.) At other times, code is so simple and manifestly obvious comments only get in the way as annoying restatements of the obvious.
I see no hard and fast rules on this front. When and how much to comment really boils down to a matter of prudence, but wondering how long it will take you to comprehend the code at hand once you've forgotten it is always a good question to ask--and how much that time might be reduced with a few more comments.
Update: After a little more searching, I found some similar sentiments from Raymond Chen.
posted by metamerist at
8:30 PM
0 Comments:
Post a Comment
Subscribe to Post Comments [Atom]
<< Home