|
My God. There are really programmers who think it's okay to write S/370 assembler without comments? I thought I'd read the whole Book of Engineering Sins, but I must have missed that page.
I can only offer one comparable instance of evil, though in this case it was an evil development tool: a microassembler for a highly unusual synchronous communications device. This lashup had five parallel processors on it: an ALU, a microsequencer, a memory access controller, and two bus bridges. Its 48-bit-wide instructions had to address all five at once, with...interesting constraints and side effects regarding timing and conditional operation.
I was handed this device, the documentation for it (which was sketchy), and the existing microprogram for it, and told to make a range of enhancements to it. Imagine my surprise when I opened up that microprogram -- approximately 4000 instructions long -- and discovered that it contained not one single comment.
Needless to say, I immediately looked up the previous maintainer, who was overjoyed that the responsibility had passed from him, and inquired about the lack of commentary. He then told me the most incredible thing I've ever been told about a development tool:
"The microassembler doesn't allow comments."
It was true. I hadn't had any idea before he said so.
I spent the next six weeks, over the strenuous objections of my management, writing a new microassembler for the damned thing. Three years later, when the responsibility for the device passed from me to a young successor, the program was fully commented.
(This message is programming you in ways you cannot detect. Be afraid.)
|
|
|
|
|
Fran Porretto wrote: I spent the next six weeks, over the strenuous objections of my management, writing a new microassembler for the damned thing.
Fran Porretto wrote: There are really programmers who think it's okay to write S/370 assembler without comments?
Yeah, unfortunately true. I left there after a year. The company declared bankruptcy the next day. I assume they decided without me there was no point in continuing. 
But I got such delight in seeing their incredulous looks as they tried to decipher their own programs after a year.
While my programs were profusely commented, I might not have bothered, they had difficulty following what I was doing. One of my first programs was to do database maintenance (back when databases were flat files). Until I came there, the "largest" program was a deck about 2-1/2" to 3-1/2" thick. I ended up carting 1-1/2 cartons (~3000 lines of code) around. They thought I was trying to write a compiler. I figured I was going to be stuck doing more database maintenance (they tended to put people in silos) and by making a macro generated generic program that I'd just have to declare a few parameters and be able to gen a new system for any other database that came my way in no time. It was able to handle multiple commands (Edit, Modify, Change, all mean the same thing) because I wanted people to be able to use it without having to read the operation manual (or as I titled it, "Care and Feeding"). As you can tell, 37 years later and I still proud of it.
Psychosis at 10
Film at 11
Those who do not remember the past, are doomed to repeat it.
Those who do not remember the past, cannot build upon it.
|
|
|
|
|
Yes, because it's a lot easier to go to some unrelated business documentation and try to find the requirement which ties to this piece of code than it is to write a line or two in the file already being read about why this method exists.
Sigh.
I hope you're able to get this person educated/fired.
|
|
|
|
|
"any business documentation should be provided by the specification and not the code."
LOL nope. Code gets updated, specs rarely do, and that's assuming that specs even exist and can be easily found. Business logic is exactly the kind of thing that should be commented, because the logic of the code won't tell you that and specs don't often go into the kind of detail that is needed when debugging a specific implementation.
The code tells you what it does, good comments tell you why. The "why" is important, because you need to know what the code should do, not just what it does, because this is what a maintenance programmer really needs to know.
I was a maintenance programmer for a long time, and believe me, commenting business logic is important. The alternative is usually running around asking all the other programmers if they remember why this code--written by someone who is no longer there--is doing what it does.
|
|
|
|
|
All I can say is B and S!
But since you said in a later post that this is from a coworker, you can do want I did when I was once told not to bother with comments in my code...
Wait a year and enjoy the puzzled and incredulous looks on their faces as they struggle to read their own code so they can modify it.
Then sidle up to them, look over their shoulders and say, "Whatsa matter? Can't remember WHY you told the computer to perform that particular operation?" Be prepared to run or withstand murderous glares.
I warned them. I learned my lesson when I had to throw out years of work because I didn't comment code and couldn't figure out how the programs worked, even though I wrote every one of them and they seemed logical at the time.
That squishy thing in your head is leaky and given enough time, fine details will fade away.
Psychosis at 10
Film at 11
Those who do not remember the past, are doomed to repeat it.
Those who do not remember the past, cannot build upon it.
|
|
|
|
|
Rubbish. 
/ravi
|
|
|
|
|
There's a lot to be said for the idea of self-documenting code... not all of it pleasant. The thing is that, while the code may well document itself perfectly in the mind of its creator, that creator might fail to take into account that many people are not exactly what one might describe as "autodidactic" and thus that self-documentation may well be lost on them.
Of course, in a perfect world, people who are unable to understand your code shouldn't be playing with it in the first place... but it's not a perfect world, and ultimately, one has to live with the knowledge that from the moment one's code hits a live environment, the catharsis of creating such brilliance is over, and at that point it becomes prostitution, with the nature of a free-for-all built in.
Code is self-documenting only if people of at least as high an intelligence as the original programmer are looking at it... but since every programmer (in his own mind, at least) is more intelligent than every other programmer, that's almost guaranteed not to happen.
My personal style is to comment at the start of procedures: "This procedure does [this], and (sometimes) here's the algorithm, rendered down into English for all you lesser mortals to understand." I might occasionally document a flag or something which is being used in a particularly abstruse way (consider, for example, the "reverse" or "multiply" - or whatever you want to call it - flag in some implementations of the Luhn algorithm for calculating checksums in credit card numbers -- that's not obvious at all).
Sometimes, the way an algorithm works isn't obvious even though the code itself is amazingly simple: for example, to describe why Euclid's algorithm (for the greatest common divisor of two positive integers) works takes pages and pages of text, involving graphs and discussions of where points converge and so on - even though a function for it looks like this:
int GCD(int x, int y)
{
if ((x==0) || (y==0)) return 0;
while (x!=y)
if (x>y) x-=y; else y-=x;
return x;
}
So in summary, then, I don't think code can always be said to be self-documenting: if the algorithm itself is abstruse (as is Euclid's algorithm) then no matter how simple the code is, the thing's still going to need to be explained. In cases like Euclid's algorithm, the best documentation may well be a link to a Wikipedia article, or something like that.
|
|
|
|
|
Hi i usually prefer self documenting code, but i write comments in the following cases:
1.- I'm writing an API that will be used by someone else
2.- The code refers to bussiness logic
3.- I'm doing something in a non standard way, usually this comes along with an explanation of why i'm doing it.
4.- I'm implementing a workaround
5.- A piece of code was particularly hard to find or figure it out.
|
|
|
|
|
|
To continue...
"Naturally, I'm not programming anything that requires more thought than a payroll program, and I have a perfect memory and everyone I work with does too, and all of them plan to live forever and never leave my company."
'nuff said.
"Seize the day" - Horace
"It's not what he doesn't know that scares me; it's what he knows for sure that just ain't so!" - Will Rogers, said by him about Herbert Hoover
|
|
|
|
|
Lol.
Speaking as someone who has worked on a number of different payroll programs, I can assure you that they do require a great deal of thought!
|
|
|
|
|
At best, self documenting code can only ever document what the code does, not what it was intended to do. The differences between the two are generally referred to as "bugs".
|
|
|
|
|
Yeah, exactly. I'm starting to think that this whole "I don't need to use comments" thing is coming from people misunderstanding what self-documenting code is. Self-documenting code is largely about readability (which is good); it doesn't mean that you never need to use comments.
Self-documenting code can reduce the need for comments, but that's not the same as eliminating the need for comments. Whenever I hear programmers making these kinds of over-generalized dogmatic statements, I assume it to be a sign of lack of experience in real-world programming, because I can't imagine how someone can program for years and not run into counterexamples.
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
