# Try to read the configuration file.
It needn't; the example I had in mind when I wrote my earlier comment was some Perl code I wrote on Friday to automate the task of taking one database, full of relations dependent on auto-increment column values, and merge its contents into another database of identical schema but conflicting auto-increment values, while maintaining the relationships between rows. This worked out to ca. 60 lines of Perl, and unusually dense and hard-to-read lines even for that language; to this, I added about a half-dozen terse but informative comment lines to serve as guideposts for my primarily Python-hacking colleague and co-conspirator on this project.
A 10:1 code-to-comments ratio is unusually high, granted, and perhaps I could've instead written the code to use a lot more temporary variables and otherwise ballooned it out to twice or three times its length, but I don't see how that would've aided readability; on the one hand, there'd be a lot more state to keep track of, and on the other, it'd no longer fit on a single screen, and would thus require the reader to scroll hither and yon while trying to make sense of it.
Some things are inherently not simple, and I'd argue that complex manipulations of complex data structures fall well within that category -- in such cases, there's only so far you can simplify the algorithm before it ceases to work as you intend. When you write such code, you more or less have to rely on the native competence of whoever else has to work with it, because there's only so much hand-holding you can accomplish either in comments or in code.
Fortunately, in this case I can safely so rely; my colleague is at least as capable as I am, so the comments I added are the same sort I'd appreciate having when attempting to digest a complex algorithm in a language not wholly familiar to me -- for example, if he'd written this code in Python, rather than me writing it in Perl.
(Of course, the real problem is that, while both languages make it possible to perform the sort of manipulation necessary here, neither language is really well suited to it; if my colleague knew Lisp as well as I do, I could've written the bloody thing in fifteen elegant and highly readable lines, and we both could go on with our lives. But I've more or less given up hope of introducing Lisp at my place of work; even the most seasoned programmers among my colleagues, when exposed to parentheses, turn pale green and make excuses to be somewhere else in a hurry.)
# EDGE CASES
# REFORMAT INPUT
# MAIN ALGORITHM
> visually represent logical segments of the code
It has little to do with how clean the code is, I can't imagine not having my way finding markers around!
Looking back, it's totally ridiculous that I would, in a professional setting, put my name next to unpunctuated writing. Aside from being ugly and hard to read, it's straight-up unprofessional.
13 open_source = tokenize.open # pylint: disable=E1101
27 # from coverage.py:
30 # In Py 2.x, the builtins were in __builtin__
33 # In Py 3.x, they're in builtins
38 """The same as s.rsplit(sep, 1), but works in 2.3"""
101 # Create a module to serve as __main__
140 # Restore the old __main__
143 # Restore the old argv and path
Start comments with a capital, have a subject and a
verb, and end them with a period.
AND that's one reason why we're not an actual profession, people.
But really, comments are one way to mislead in code. If a comment is made that incorrectly states the intent of code, it's undeniable that this is harmful to the readability of the code.
Comments may mislead yes, but that's a problem with any sufficiently expressive language, and code is one such language: code can mislead. The functionality required of the code may be only half-implemented, then that code is misleading. That code may work for certain easy cases, but it may be harmful to your understanding of what functionality is actually required.
It's easy to see why we prioritize code over comments, why we prioritize the mechanisms over the specifications. It's because code can have some manner of automatic verification, and we're too harried to look into the comments, to do code review. Deadlines abound. We can't stop work and say, no, we can't do this under these time constraints without sacrificing a minimum level of quality, specifically because we're not treated like an actual profession with the clout or the responsibility that comes with such a thing.
And I can say "this can't be done under these time constraints" at my job. If you can't, then you're not being taken seriously because of some other reason, not because you're a programmer.
Who cares about these things, which don't change the code? Anyone who needs to understand the code, which includes anyone working on it, including its original author - writing a brief explanation of a tricky point can help you spot mistakes before you compile or test, or even before you write the code. The goal is to produce correct code, not just code, and the one thing that is faster than continuous testing is avoiding mistakes in the first place.
FWIW, I think the idea that comments need to be complete sentences is silly. Sentences can be as wrong, ambiguous, misleading or uninformative as simple phrases.
You don't need comments to run code.
I think the only thing really stopping software development from becoming a formal profession is a standardized code of ethics (of which there are several proposed) and a professional body to govern it (and let's face it, professional bodies can exert power to satisfy immoral agendas, much like unions).
Professionals are allowed and expected to dedicate about half their working time to career development and continuing education. Many software engineers will get fired if they get caught in that.
This is pretty much false.
Honestly, given all of this, I don't even think software development becoming a profession is desirable at all.
Speaking of which: any good tools for literate programming?
Clear, even verbose commentary can be helpful. But where it often breaks down is when the code is revisited, and the comments are not updated as well. So my practice now is to use comments in early development to help me remember what I was thinking in that bit of code, but then remove most of them during clean-up and refactoring unless something particularly non-obvious is going on. It makes future maintenance of the code less likely to diverge from the (usually unmaintained) comments.
Good code review could help here: "Hey, the diff shows you changed six lines of code in that function but the comments are the same, do they need to be revised?" But I've never worked anywhere where EVERY commit was reviewed, rather a sampling is selected for weekly review. that leaves a lot of opportunity for things to get missed.
Bottom line: extensive comments can add to workload when fixing bugs or making enhancements. So only use them when they really count.
Too often I've found that vast amounts of effort were put into keeping something "readable" to the point that all of the extra readable hints either just got too large and unwieldy, or it prevented the developer from picking an easy and straight forward solution. (And to be fair, often that developer was me.)
I think there is a very real divide between what the logical flow for a computer to be presented something and the narrative flow for explaining that to another developer are. And no amount of clever variable/function names will really help here.
In fact, often times it can be worse. The proverbial isle of a grocery store. Too much to look at with no obvious "main" method. There is a reason it is a "rookie mistake" to have giant methods that do too much. When it comes down to it many people were only trying to get their program to do one thing. Cluttering their memory with the myriad steps necessary to get there is a large hurdle to get back into something.
The article does make one good point: that when you add to a terse comment you often have to add capitals and punctuation. But that is also often a signal to me to ask why I need to switch from communicating a fact to creating a narrative. Is the narrative really necessary? Often I find some way to reorganize the code without needing to narrate it. Relevant is http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.htm.... (But I'm not claiming everybody who uses complete sentences is a noob.)
// 1. Write plain English psuedocode.
// 2. Translate into scary looking code blocks.
// 3. If maintaining, remember to update comments first (goto Step 1, then Step 2).
The irony is another developer once claimed that my code was generated by a machine. Apparently it was too methodical to be human. Like that was some excuse for him to write crappy code. Urgh! To be great at anything, you need to have excellent communication skills!