I'm Just Sayin'

[billroper]

Have you ever noticed that some programmers comment their code like their job security depended on it? As in, if there are no comments in the code, then their job is secure, because no one will ever be able to decipher the code?

I'd think this was learned behavior, except that my formative programming experience was as a junior systems programmer on the PLATO system at the University of Illinois and none of the junior sysprogs there (except for me) commented their code either. And you know that they weren't planning on being around for a long time. (We had a shortage of Zonker Harris clones.)

I'm just sayin'...

Comments

[fla-sunshine.livejournal.com]

Yeah, I once had to try to decipher and modify an ASSEMBLY language program for which the ONLY comment in the ENTIRE program (a page or two of code) was one that said "This line may have to be changed". I think I eventually gave up and wrote a new program from scratch.

[avt-tor.livejournal.com]

That's the manager's fault. If there's no style manual, or if it isn't enforced, can't blame the code monkeys. In the real world, people are going to change jobs no matter what you do. A well-run organization uses a sort of open-source paradigm, in which employees are valued on the amount of information they share, not the amount they hoard.

If code without comments is rejected, or if people have a performance component of their compensation that requires comments, or if the coder gets fired for not doing the job, people will learn. It is also the responsibility of project owners (i.e. executives) to include time/money for comments in the project plan; if the manager is given the directive "give me something that works by date X" then comments will be deprioritized.

With logical (and consistent) indentation and variable and function names, the amount of comments required should be minimal. Unsupportable code does not necessarily lead to job security, it can lead to hiring new programmers to reverse engineer the output. (Of course, that requires hiring managers who know how to manage programmers.)

[rono-60103.livejournal.com]

I suspect it is subconscious ego at work. I know that is why I'm bad at putting in enough comments in code I don't expect anyone else to look at.

I have this bad habit of thinking "right now it is 100% obvious what this block does, I don't need to put a comment here." You'd think after having to figure out what the code I wrote ten years -- or a week -- ago did more than once I'd learn. But the program I'm working on right now probably doesn't have all the comments it should.

[giza.livejournal.com]

/**
* I write comments like I'm going to get hit by a beer truck the next day.
*
* Plus, it keeps me from having to remember what I was doing when I get back
* to that code 6 months later.
*
*/

[billroper]

A man after my own heart. :)

I've been maintaining some of this code -- in one incarnation or another -- for nearly 25 years. I know I'm going to forget what I was doing when I wrote some of it.

[madfilkentist]

I've noticed that problem throughout my career. Perhaps the simplest explanation is that most programmers find it a great effort to write even simple English prose.

[dek9.livejournal.com]

I'm a freak in that I comment the hell out of my code. But I do that as much for myself as I do someone else. I can't tell you how many times I've had someone come up to me 6 months after I worked on something and ask me why I wrote something. If there are comments either 1) I'm more likely to remember or 2) they may not ask to begin with.

I've had other people who were learning how to code tell me they loved reading my code because they could follow what I was doing and actually learn coding from real live code.

[mbumby.livejournal.com]

I try hard to comment well, when I have the time, even when all I need to do is change a small part of someone else's code -- if it's in a part of the program I needed to figure out I never want to have to work that hard to figure it out again. Unfortunately, what I find to be exceptionally verbose today I often discover to be unintentionally ambiguous 3 years from now (especially, although not exclusively, if someone else changes pertinent parts of the code without changing the comments).

[pheltzer.livejournal.com]

I comment the hell out of my code. Mostly as a result from never getting more than 20 minutes at a time to focus on code. I'd never know what I was doing if I didn't. Add on to that inheriting someone else's code with if it were possible less than zero comments and swearing I would never do that to someone if I could avoid it. Part of the whole... "You can bitch about the problem, or you can try to fix the problem" mentality.

[tigertoy.livejournal.com]

PLATO programmers had an actual reason for not commenting their code that nobody today can claim: the amount of storage space the comments in the source took up was genuinely significant and expensive. A lot of PLATO people learned to program only having access to a few parts (for those of you who don't remember or never knew what a "part" is, it amounted to 22400 six-bit characters, and there was further inefficiency in the data format, so in practice that was less than 20K characters), and not commenting (or more horrifyingly, stripping existing comments out) made it possible to write more program. Despite that, in my own experience as a junior sysprog, just after you left, the junior sysprogs (who should have been closer to the experience of learning to program in the space they could scrounge) were far better at commenting than the senior staff or most of the rest of the programmers on the system. (Not actually good or even adequate, mind you -- just better.)

Bad programming is certainly a learned behavior pattern, but I doubt that it's learned intentionally, except in cases where people learn to do what their boss tells them to do even when they know it's stupid. As I see it, the problem is that good programming practices are seldom taught and almost never reinforced. I've been in several workplaces that made noises about having coding standards and real code reviews, but never one where the managers were actually willing to take the time to have code reviewed (and fixed by the coder and rereviewed until actually acceptable). It takes longer to get to nominal feature complete that way, and the fact that it will take less time to get from feature complete to genuinely releasable and less time to do future releases doesn't matter, because corporations are all about immediate results and managers are trained to think that way. (How many managers have you seen who would rather let the schedule slip than ship a shoddy product that they could claim met the specs? How many managers' managers would reward letting the schedule slip with a bonus rather than a severance package?)

[phillip2637.livejournal.com]

http://mindprod.com/jgloss/unmaindocumentation.html

[drawshad.livejournal.com]

I comment my code within reason. I have more than the average bear, but don't like to write verbiage to explain fairly clear cut code. Do I really need to comment "if (countOrders > 10) then do this"? I usually only define weird business rules

The biggest problem I have with non-commenters is they tend to write the worst spaghetti code and then never have the time and/or patience to explain it to me when I have to fix/change something.

[scarfman]

It's more likely that commenting is learned behavior innit?

[lensedqso.livejournal.com]

I actually got yelled at for commenting my code at my first programming job. My boss (well, actually my boss' boss) considered it a waste of time and a form of procrastination.

[madfilkentist]

It takes longer to get to nominal feature complete that way, and the fact that it will take less time to get from feature complete to genuinely releasable and less time to do future releases doesn't matter, because corporations are all about immediate results and managers are trained to think that way.

I work in a university. It's no better there.

[mdlbear]

Exactly.

I usually write the declaration for a function and a brief comment simultaneously, when I first discover that I need it, and write the body sometime later. Which might be much later, if I've been called away to work on something more important for a while. Or just get distracted while I'm having lunch.

[poltr1]

I have to comment my own code while I'm writing it. Otherwise I'll forget what the hell I did last month. I typically write 1-2 lines of comments for 10 lines of code.

When I worked as a remote batch terminal operator at college, I noticed that some of the engineers wrote very dense and cryptic FORTRAN code. When I asked one about comments, their response was something like "The compiler ignores them, so putting in comments is not efficient."

[billroper]

Well, some of us seem to learn... :)

[billroper]

Bad boss! No donut!

[billroper]

Yup. Declaration goes in and the comment goes on.

I will sometimes skip the comment for simple event handlers, because they're generally easy to trace from the message map. But that's an exceptional case.

[mdlbear]

And sometimes the name is all the documentation you need, especially in some of the more verbose languages like Java. getFoo(), setFoo(v), getBufferedReaderOnFoo()... and so on and on.

[mdlbear]

One of the other good reasons to write comments, by the way, is that you get some of your documentation for free. Java has javadoc, of course, but it only takes an hour or so of Perl hacking to turn suitably-formatted comments in any language into HTML, LaTeX, or whatever your favorite documentation format is.

[starmalachite.livejournal.com]

Good grief, hasn't anyone driven a stake through LaTeX yet? As a tech writer, I still occasionally have bad flashbacks from being forced to use it for 7 years. It makes MS Word look well-designed and isn't even WYSIWYG.

[billroper]

Yeah, we have a tool (Surveyor) from Starbase that will produce pretty good documentation from my code. :)

[mdlbear]

Hasn't anyone driven a stake through the WYSIWYG myth yet? I use LaTeX and HTML precisely because they're not WYSIWYG: they're plain text that I can edit with the same text editor I use for everything else, process through various scripts, and generate automatically.

There's no way I know of to generate Word documents in Perl; LaTeX and HTML are easy. I can run a Makefile over my code tree and get typeset documentation in LaTeX, online documentation in HTML, and an installable application all in one command. And text is easy to manage in a version-control system, which gives me a changelog and a report of differences for both my code and my documentation.

... and there are a couple of WYSIWYG editors for LaTeX if you're foolish enough to think they'll make you more productive.

[starmalachite.livejournal.com]

I use LaTeX and HTML precisely because they're not WYSIWYG: they're plain text that I can edit with the same text editor I use for everything else

Not an issue in my case. I wasn't even documenting a software product at the time; I was producing user manuals for the Hubble Space Telescope. LaTeX was used because it was the only tool then available (1987-1993) that could properly typeset heavy-duty higher mathematics.


I can run a Makefile over my code tree and get typeset documentation in LaTeX, online documentation in HTML, and an installable application all in one command.

OK, under those circumstances LaTeX would be useful. I'll grant you that it has a reason to exist after all. However, if you were using LaTeX *only* as a glorified word processor (as I was forced to -- not my call) even Word would start looking awfully good by comparison.

Looking back, I think a lot of my ire at LaTeX comes from how difficult it was to tweak the template defaults for spacing and font size. (They didn't match the local style guide, and were ugly to boot.) Certain values would crash the Makefile run every time, while the next increment up or down would not.


there are a couple of WYSIWYG editors for LaTeX if you're foolish enough to think they'll make you more productive

Not if I were a programmer. But great Ghu, yeah, that would have made *me* more productive back in the day. Trying to produce camera-ready copy without WYSIWYG is like typing on an old manual typewriter in pitch blackness with sledgehammers for fingers. If you're good and persistent, you'll do it eventually, but you'll waste an awful lot of paper and the end result won't be nearly as pretty. Been there, done that, see no need to repeat the experience.