(20:49:20) <Zhivago> Comments indicate defective code.
(20:49:31) <Zhivago> So the more comments, the worse the code.
(20:49:51) <Zhivago> On the other hand, a lack of comments can indicate uncommented defective code.
As usual, Zhivago is acting like an elitist faggot, back with his circlejerking friends in ##C. Sure looks like someone should step up and send him a /prog/ invite, I think he'd fit in perfectly.
Name:
Anonymous2011-07-15 18:44
Good code doesn't need explanations because good code explains itself. I've worked at Microsoft for about 3 years now, and they've never complained about me not commenting code.
Good code doesn't need explanations because good code explains itself. I've worked at Microsoft for about 3 years now, and they've never complained about me not commenting code.
I'm going to stay the fuck away from Microsoft so I don't end up maintaining your code.
Name:
Anonymous2011-07-15 20:06
>>5
Umm, he was kidding. Actually, Microsoft code is generally loaded full of comments. I'd say there's more comments than actual code. I generally don't think that's a good thing though. Just look at the Microsoft .NET CLR source code that they open sourced, or even the old leaked DOS 6 source code.
>>1
Comments should be much more important in an imperatively written program as most functions depends on state and actually does not explain themselves.
Also there is nothing wrong with documentation strings like those you can add in Common Lisp.
It's just as hard to write good comments as it is to write good code, most devs only know the latter and thus dismisses the first as unimportant.
Name:
Anonymous2011-07-15 21:42
they aren't necessary as long as the language has significant indentation
>>14 ONE WORD: THE FORCED ONE LINERS TO AVOID THE FORCED INDENTATION OF CODE.THREAD OVER
Name:
Anonymous2011-07-16 3:27
Comments should be to explicate surprising situations.
This is pretty much the biggest reason for commenting the code. Having too many comments can result in comment rot for code that is frequently refactored.
Name:
Anonymous2011-07-16 4:00
I dislike comments that just reiterate the code.
I like comments that are suggestions as to use or example uses or explanations of something kind of weird.
Also, in most languages you need to express non-trivial invariants that the type system can't check with comments.
Name:
Anonymous2011-07-16 5:02
Write comments only where the code is incapable of explaining itself.
Prefer self-explanatory code over explanatory comments. Avoid
`literate programming' like the plague.
Rationale: If the code is often incapable of explaining itself, then
perhaps it should be written in a more expressive language. This may
mean using a different programming language altogether, or, since we
are talking about Lisp, it may mean simply building a combinator
language or a macro language for the purpose. `Literate programming'
is the logical conclusion of languages incapable of explaining
themselves; it is a direct concession of the inexpressiveness of the
computer language implementing the program, to the extent that the
only way a human can understand the program is by having it rewritten
in a human language.
/* Code that prints the range of numbers starting from 0 inclusive to 10 inclusive
This code prints the range of numbers starting from 0 inclusive to 10 inclusive
Copyright (C) >>20 */
#include /* This is a preprocessor statement that includes the source code of another file, */ <stdio.h> /* and that file is the standard library's <stdio.h>, that contains
the standard I/O procedures and definitions. */
#include /* This is another preprocessor include statement, */ <stdlib.h> /* the standard library include. We need this for some standard macros and definitions. */
signed int /* This function is declared as `signed int', it means that it will return a signed integer
between `INT_MIN' and `INT_MAX'. (see <limits.h>) */
main /* The name of this function is `main'. `main' is a special function in C, it defines the entry point
of the program. Every program must have a `main' function, so here it is. */
( /* This opens the argument list for `main'. */
signed int argc, /* The argument count variable, it is passed as an argument to main when you start the program.
It contains the count of the arguments passed to the program. It is a signed integer. */
char *argv[] /* The argument vector pointer, it is passed as an argument to main when you start the program, just like `argc'.
It contains the actual strings of the arguments passed to the program. It is a vector of `char*'s of the same
length of `argc'. */
) /* This closes the argument list for `main'. */
{ /* This opens the body of `main', here goes the code. */
signed int i; /* We declare a `signed int' variable called `i'. It will be used as index variable for a loop later in the program.
The `i' name comes from FORTRAN, that took it from mathematics, and stands, surprisingly, for index. */
/* Leaving a space between variable declarations and code is good style. */
for /* We will be using a looping language construct called `for'. It can be desugarized as:
for (init; cond; incr) body;
{init;while(cond){body;incr;}}
, except that if a `continue' or `break' statement is executed, the `incr' part will be executed as well. */
( /* This opens the ``argument'' list for `for' */
i = 0; /* As `init', we set the `i' index variable to 0. */
i <= 10; /* We will be looping for all the numbers from 0 inclusive to 10 inclusive, so we check if `i' is less or equal than 10. */
i++ /* We increase `i' */
) /* This closes the ``argument'' list for `for'. */
{ /* This delimits the `body' part of our `for' loop. It is good style to delimit the body of a loop with brackets even if the language
permits one statement bodies to be undelimited, just to be sure that if we will ever add some code to the loop we will know that
it will work no matter what. This decreases mistakes in the code. */
printf /* The `printf' function stands for print formatted. It will be used to print the value of our `i' variable.
The `printf' function is pretty sofisticated: it takes a format string as first argument, and the printed values as
rest arguments. The format string and the types must coincide, though, because `printf' is not type safe.
It is defined in <stdio.h>. */
( /* This opens the argument list for `printf'. */
"%d\n", /* This is our format string. Nothing too complex, just the %d format specifier that says to `printf' that
we will be printing a `signed integer', and a \n that means a newline. */
i /* This is our `i' index variable that contains a number starting from 0 inclusive to 10 inclusive. */
); /* This closes the argument list for `printf'. */
} /* This closes the delimiter of our `for' loop's `body' part. */
return /* We return a value to the OS. */
EXIT_SUCCESS; /* We return a success value, because we have successfully printed the range of numbers starting from 0 inclusive to 10 inclusive. */
} /* This closes the body of `main'. */
>>13
He's still an elitist faggot of the worst kind.
Name:
Anonymous2011-07-16 19:00
Documentation should be primary, code secondary. Literate Haskell neatly embodies this -- allowing you to essentially write your Haskell code as a .tex file.