This topic was created by Parax .
"Well, obviously a "C" programmer's comment will have made sense to them when they wrote it but, while syntactically and grammatically correct, will be impenetrably unintelligable to anyone trying to make sense of it later."
I think that might be Perl you're alluding to - surely the king of write-only languages.
As distinct from a Java coder's comment which tends to look like this:
/**
*foobar
*this function bars Foos and returns a Snafu
*@param bar a Bar
*@param foo a Foo
*@return a Snafu
*/
private Snafu foobar (Bar bar, Foo foo) {
//Create a new Snafu passing bar and foo as parameters
Snafu snafu = new Snafu(bar, foo);
//do something with the data
snafu.doSomethingWithThe Data();
//now return the Snafu object
return snafu;
}
I think they get paid by the line, including comments
I think they get paid by the line, including comments
I do a lot of Java. I doc the shit out of my method and class headers, because it makes code inspection and merging later far easier, and the IDE will pick up on them. Within my methods though, I keep the comments to what's required. I go with the philosophy that comments should not explain what you're doing, but rather why you're doing it.
This post has been deleted by its author
A Linux programmer - "Comments are for newbies."
A Windows programmer - There is no point in writing comments because the language of the day changes far too often. ( 6 months is already an old coding library - .DotNet - no problem, which version/sub version, MFC anyone, WIN32 -- WTF is WIN32).
A Cobol programmer - If someone needs to read comments to understand Cobol , they also need to change their profession.
A RPG programmer - Does anyone still code in RPG......
A Basic programmer - No need to write comments , they never get further than line 20
10 : Print "My name is Michael"
20 : Goto line 10
An HTML programmer - <!-- This is commented out -->
I once had the job of rewriting a program written on a BBC micro to control a test instrument, using BBC Basic and written by a physicist. It needed to add an auto calibration routine and some data logging, but it did the job.
The program was beautifully written and well commented. It was a pleasure to work with, the best piece of code I had seen in years.
But I soon fixed that. We can't have these non-programmers coming in and raising the standards.
This just happened to me!
Except that the comment was less obviously a "to do"
two end cases to handle in an algorithm, he handled the second, but had the detection for the first as well. The comment said something like "increase gain here" followed by several lines apparently modifying some gain parameters (but not actually increasing anything).
d'oh.
Which is why one of the last things I do before committing any code is have the IDE look up any @todo tags in my current module. ;-)
Think my favourite comment was from my old boss, who left in one class:
"I think I've got this working, but then it was written by <ex programmer>, and <ex programmer> was a lazy incompetent twat."
I've left comments like that.
Worked with a lazy shit once who never documented the IP addresses assigned to 3rd party VPN NAT pools, so I used to mark them as..
"<the lazy twat> has assigned these addresses to someone - I suggest you ask him. [date]"
6 months later the file was still full of them - I think it's still that way to this day. God help anyone trying to audit them. (This was for a well known internet bank as well).
We were integrating some code from a third party once, and one of the developers found code which alloc'ed memory, and if it failed executed:
printf("Fuck me! No memory left\n");
exit (1);
He sent mail to the team asking "Should we change this?", to which our manager immediately replied "Of course, it isn't internationalized".
Ah, for the fun days programing for a young company with money :(
I did once have a customer contact me and ask why he'd gotten the error message "Well, you fucked that one up, didn't you you twit?" Turned out his server environment wasn't configured properly, so a should-never-happen condition...happened. Fortunately, the customer had a sense of humour and I got away with it.
I've used that kind of thing, and seen the errors appear for real an enhancement or two later.
It anticipates the possibility of future code change, as in a class you intend always to be overridden, but implement stubs for. Or even simpler, this sorta thing:
enum { foo, bar } x;
...
switch (x) {
case foo: do_something; break;
case bar: something_else; break;
default: fputs("BUG: unhandled enum value in ...", stderr);
}
While testing software at a place I used to work at a million years ago, a windows mode (back in the DOS days) program if run under DOS would result in "This program must be run under windows" or words to that effect.
Except this one: "This program must be run under windows you dumb fuck" or words to that effect.
I don't remember if we found out about it first, or the client(s), the programmers probably had a few stern words said to them though.
Years ago I had to port a rather large body of C++ code, with which I was completely unfamiliar, to Linux. At some point I came across a header file that was #included all over the place but contained nothing but a comment. It said, roughly,
// Since AIX has WIN32 API emulation now we can throw away
// the whole UNIX branch.
This post has been deleted by its author
XEmacs has lots of vigorous comments, as you would expect from something on which Jamie Zawinski worked. Such as
/* #### urk urk urk!!! Chuck fix this shit! */
and then a few hundred lines later
/* #### Chuck fix this shit or I'm gonna scream! */
The comments are at least 15 years old, and Chuck (who is still around) still hasn't fixed them.
(#### is code for "major screwage that should be fixed for the next release")
There ain't no passive aggression in XEmacs!
This post has been deleted by its author
This post has been deleted by its author
Hardly. Old-school assember newbie who didn't know what a macro or a pseudo-op was.
You'd code
SWAP R1,R2
and the macro or assembler would generate the sequence of XORs if that was the most efficient way to do it on your CPU. If the hardware vendor hadn't written it for you, any self-respecting assembler programmer would have written it for himself.
I once saw an enormous macro to implement
SETCONST register, value [,scratch_register]
which avoided loading a constant from RAM for about a thousand commonly and less commonly used constants on an early instance of what would later become known as a RISC architecture.
Year 200 is arriving. I was involved in making a VAX VMS 2000 safe.
But unfortunately nobody (hired in help) could find the files to do the date changes ?
The reason was (that I sussed) was each file name had an extra space at the end ("do_data_search " et al), so obviously they was written on a a dubious platform then FTP'ed to the box.
Monkeys or Sheeple?
Nick
comment every line.
how else will anone understand register indirect addressing witth auto increment/decrement?
Cobol Programmers using punched cards start theit comments at column 73
Forth Programmers don't comment. Every bit of their code is self describing to other Forth programmers.
Yes the above comments show my age.
"Forth Programmers don't comment. Every bit of their code is self describing to other Forth programmers."
All kidding aside, I've found Forth programmers the most reliable of documenters, partly due to the old tradition of shadow blocks which practically sucked comments out of you.
I've written code like that before. Do you shift gears in your brain into 'machine mode'? I do, and all the world seems to vanish and all that is left is problem space. Some code I then generate seems straightforward but I can't understand it when I try to analyse it. Upon exiting the 'zone' I felt exhausted, much as oracles of ancient times were reported to have been when the god released them from their trance.
The 'zone' ultimately became a frightening place for me.
I can't believe that nobody has yet posted Dennis Ritchie's famous comment from the context switch code in the middle of the Version 6 Unix kernel, something which has passed into hacker folklore:
/*
If the new process paused because is was swapped out,
set the stack level to the last call to savu(u_ssav).
This means that the return which is executed immediately after
the call to aretu actually returns from the last routine which
did the savu.
You are not expected to understand this.
*/
Around 1995 Hobbit wrote "netcat", a useful little telnet/web-broswer substitute. It contained delightful comments, including this:
/* I really want to strangle the twit who dreamed up all these sockaddr and
hostent abstractions, and then forced them all to be incompatible with
each other so you *HAVE* to do all this ridiculous casting back and forth.
If that wasn't bad enough, all the doc insists on referring to local ports
and addresses as "names", which makes NO sense down at the bare metal.
What an absolutely horrid paradigm, and to think of all the people who
have been wasting significant amounts of time fighting with this stupid
deliberate obfuscation over the last 10 years... then again, I like
languages wherein a pointer is a pointer, what you put there is your own
business, the compiler stays out of your face, and sheep are nervous.
Maybe that's why my C code reads like assembler half the time... */
.
.
.
Then there's this little gem:
/* some systems, notably linux, crap into their select timers on return, so
we create a expendable copy and give *that* to select. *Fuck* me ... */
if (timer1)
memcpy (timer2, timer1, sizeof (struct timeval));
rr = select (16, ding2, 0, 0, timer2); /* here it is, kiddies */
if (rr < 0) {
if (errno != EINTR) { /* might have gotten ^Zed, etc ?*/
holler ("select fuxored");
close (fd);
return (1);
}
} /* select fuckup */
Somewhere in the system timer interrupt code, back in the days when you got the source of the entire VMS operating system on Microfiche with every new release ...
; Does anybody really know what time it is
; Does anybody really care
; If so I can't imagine why
; We've all got time enough to die
(which is of course a quote of a lyric by , IIRC, Chicago).
"A good Smalltalk method probably only has one comment, which describes what the method does. Everything else should be pretty understandable from reading the code. If it isn't, that's usually the fault of the coders (the reader, the writer or both) rather than the language. Any method big enough to need inline comments is usually too big to be a single method, and should be a considered a candidate for refactoring."
^self commentOnly
;I don't remember exactly why I wrote this shim, nor what it does
; It was late, I had several beers ... you've been there, admit it
; But don't change it or everything else breaks!
It's been in my personal `.fortune` file since I first ran across it :-)
The programmers I've been dealing with don't comment. They even go to the trouble of removing comments that support staff put in to guide them. (because "they aren't required"). All code is self-documenting, and if you want to find out what it does, just read the code. Commits (when they have them - most of the code isn't in a repository) have things like smiley faces or "fixed" as the comment. After all, it will be obvious what they intended for the code to do, as opposed to what it actually does.
No, I'm not fond of the programmers I've been dealing with lately.
I worked with a guy once who never commented code because "it was hard to write, it should be hard to understand".
His boss went completely the other way: she was converting code from one tool to another and in the middle of the most important section she had a comment "Didn't understand this bit so left it out" - so comments instead of code. What could possibly go wrong ..?
I'm distinctly old-school - I cut lots of COBOL code in the late 70s and early 80s. I'm part of the reason you had all that fun re-writing it in 1999 ;-)
Two particular memories from having to amend programs others had written:
1. A long program (about 10,000 lines of code excluding the Data Division) which was generally well commented. The comments were brief, to the point and helpful except for THAT section. This was a chunk of about 1,000 lines of incredibly intricate code that used some of COBOL's more obscure functions in very "creative" ways. It had one single line comment at the very beginning which began with the unforgettable words "This section simply..."
2. Amending a program that had been amended and added to by three programmers before me in addition to whoever wrote it. Clearly whoever had done one of the amendments had had a bad time with whoever wrote the spec because two of the data items he had defined two were named "NEVER-MIND-WHAT-YOU-MAY-HAVE-HEARD" and "JUST-STICK-TO-THE-BLOODY-SPEC".
Ahhh... happy days!
(Beer - 'cos I wrote some of my best code after two-hour boozy lunchtimes!)
We have just taken over a project re-write for a client, and i just got the old source code, all VB - and not one comment in the entire source code - also its the first time i have looked at vb since about 1997... i would like to remind the readers of the tao of programming...
Thus spake the master programmer:
``Though a program be but three lines long, someday it will have to be maintained.''
and this one is 3 lines long.
We are converting it to a web based system, but i am still like WTF can you program with *no* comments at all.
Also - please refer to http://xkcd.com/224/ :D
I once worked with a smart arse whose rationale for not putting any comments in any code was that they would slow down execution of his apps. Now, just to be clear, we're not talking about interpreted or JIT-compiled code here. Later after wearing him down some, his argument reduced to the comments slowing down interpreted code, so we organised a little test in the office with HEAVILY commented vs uncommented version of a script of his, and ran benchmarks on them - we were unable to measure any difference between them...
Oh, and the "rule" for a long time at another place I briefly worked was that comments had to have jump instructions around them - to avoid programs being slowed when "processing" them! Even batch files were not spared - every comment had to be preceded by a GOTO statement jumping to a named label:
@Echo off
GOTO SkipREM1
REM ***********************
REM * This is a comment
REM ***********************
:SkipREM1
The "most informative" comment I ever saw was on a non-trivial piece of Perl. Most of the code was undecipherable in the first place, but the most complex part was blessed with a single comment (the only one in the whole script) that simply read:
# This is a skanky hack!
We started off with quite a well-commented application. Since we offshored, our offshore friends' favourite trick is when we need something that's similar but not quite the same as a bit of existing code (e.g. a stored procedure), they copy and paste, and modify everything...except the comments, which remain identical to where they copied it from and tell you nothing about the new code. This is now all over the codebase, every so often if I see one I try to fix it, but it's a losing battle...
A customer agreed to pay (a small fortune) to have access to the source code at the end of a managed service period and so it was sent through to them with a big fat ribbon on top. A long term problem that had never been fixed properly despite seven years of work was reviewed by them and they found a comment with a date five years earlier saying "I have no fucking idea what this portion of code does".
So, how about a slice of humble pie that comes direct from the oven of shame set at gas mark 'egg on your face'? And perhaps a sizable discount on that code?
Once upon a long ago I worked on a DEC PDP 11/44. I was part of a COBOL team but we also had another team doing work with a "high-level" BASIC provided by DEC (BASIC+2 or summat). Comments were required even for the manky BASIC, and I was reviewing something after one guy left the project. All his code was in handy chunks of 15-20 lines with nearly as many comment lines between...
However...
All his comments were verses from a Thousand and One Arabian Nights...
The Register 
Biting the hand that feeds IT
Copyright. All rights reserved © 1998–2024
