Print

Please login or register.
1 Hour 1 Day 1 Week 1 Month Forever
Login with username, password and session length

[Dutrius]

I often attach a comment to any line that contains something temporary that says something like this:

Code: [Select]

string foo = "bar";      //Temp. (brief explanation of why)

Debug statements often say something like:

Code: [Select]

Debug.writeline("Doing something.");
Something();
Debug.writeline("Doing another thing.");
AnotherThing();
Debug.writeline("Done.");
If the log says "Doing something." and not "Doing another thing." then you know it failed at AnotherThing().

[Reelya]

Another handy one is to put a debug at the start of functions saying what parameters they were called with,  such as "called <function> with <parameters>" and one at the end, saying "completed <function>" . so you can check whether the parameters look normal, and check that there's a matching "completed" statement. On occasion I've even set up a debug print command that knows how to indent, so the debug log gets indented according to call depth.

[Levi]

Welp, I just found the strangest Ruby bug I've ever seen.  Only happens in Windows.

Code: [Select]

Dir["Com3.asdfasdf"]

It should return [], but instead it returns ["Com3.asdfasdf"]. 

Anything that starts with Com3, Con, or Nul gives false file reports.  These are all reserved filenames in windows, but also seem to cause this bug when scanning directories in Ruby.

[Moghjubar]

Thanks Reelya. That feedback was actually really helpful; it's very easy to learn how to program, as in learning the syntax of a language, but it's difficult to learn how to be an effective programmer.

This is what I say: programming is easy, development is tough, and then there's engineering and architecture if you want hard mode.

[miauw62]

Yeah, programming is easy until code you wrote a month suddenly stops making sense.

[Putnam]

yes, when programming avoid this:

// you're not dumb you know what this does

this just leads to a lot of "fuck you past me"

[Levi]

yes, when programming avoid this:

// you're not dumb you know what this does

this just leads to a lot of "fuck you past me"

Heh, comment lines I wrote in some encryption code that I came across again recently:

Code: [Select]

#WARNING!  DO NOT MESS WITH THIS CODE.  NOT EVEN YOU LEVI!
#If you are ignoring that warning, make sure you understand EXACTLY WHAT and WHY
#each bit does, otherwise I can't guarantee its security. (I won't even guarantee it now)

[i2amroy]

Reminds me how I was perusing the web code for one of my college's websites recently and saw this gem:

WARNING: THIS IS A HORRIBLE HACKY WORKAROUND AND I CAN'T FIND WHAT'S WRONG! SOMEONE PLEASE FIX THIS!!

As best as I could tell that particular bit of code has been there for at least 4 years now... in the middle of one of the most commonly used homework submission sites on the campus.

[Orange Wizard]

My old projects are littered with unhelpful comments.

I'm not sure how this works, but it works, mostly

This is a dumb way of doing things but changing it makes [completely unrelated module] crash

Future me, don't look at this or you'll go blind

This should do X but it doesn't

[Bumber]

yes, when programming avoid this:

// you're not dumb you know what this does

this just leads to a lot of "fuck you past me"

CURRENT Putnam [CP] began trolling PAST Putnam [PP]

[Antsan]

Huh, I mostly use comments when presenting code for other people, to work out an interface before actually implementing it (and when that is done, the comment is removed) or split code into sections, but almost never for documenting how something works, what it does or what it is intended to do. If I don't understand something I wrote a while ago I normally try the parts and see what they do.
On the other hand I often rewrite passages I don't understand anymore. Also I work with Common Lisp and Haskell, in which most code is sufficiently self-documenting and trying arbitrary code is trivial. In Poslin I use stepping to find out how something works.

A warning I have seen some times in regards to comments: They are prone to getting out of date if you fix a bug or refactor. Then they aren't only useless but might even cause confusion when you spot a difference between what a comment says and what the code says.

[LoSboccacc]

same here, no comments

if the code smells so much you're tempted to comment it, move it to it's own method until it became clear and name the method as you would explain the operation in the comment.



above all thing, all developers should read code complete.

[itisnotlogical]

I don't believe "self-documenting code" is the be-all end-all. Just because everything is easily readable and makes total sense to you doesn't mean it will be as readable to anybody else that's poking around, or even to yourself a few weeks down the line when you've taken a break. Comments are a tool, just like an IDE or a compiler.

[Telgin]

I used to comment my code as a sort of "distilled" version of the program.  That is, I'd write:

Code: [Select]

// Look up the gateway
api.gateways.find({where: {site_id: req.param('site_id'), production_state: 'production'}}).then(function(data) {
    // Stuff
});

The comment is so much faster and easier to parse than the line after it, even if the line after it is pretty clear if you work with the project very much.

Despite that, I got out of the habit because the comments tended to rot and they didn't add much clarity in the end.  In general, the methods and functions were short enough that you could quickly determine what a block of code did without the comments, and only if the code because particularly obtuse (callbacks or other abnormal control flow) would I add comments.

Or if a library or something had a stupid API that made me jump through too many hoops.  Then I'd write an angry paragraph explaining why I did what I did to get it to work.

[Antsan]

I don't believe "self-documenting code" is the be-all end-all. Just because everything is easily readable and makes total sense to you doesn't mean it will be as readable to anybody else that's poking around, or even to yourself a few weeks down the line when you've taken a break. Comments are a tool, just like an IDE or a compiler.

Self-documenting code isn't the be-all-end-all, you're right about that.
But with Common Lisp/Haskell/any language with a decent Syntax I don't only have code I can actually read comfortably (as opposed to something like what Telgin just posted) but often there are other features which help mitigate the necessity of comments.

Haskell has its types, which function effectively as a part of the specification that can be programmatically checked, so they are never incorrect or out-of-date.

Common Lisp and Haskell both have a REPL (although the one for Haskell is quite incomplete), so if you don't understand what a certain part of the code does, you can just check immediately. Note that this doesn't prevent compilation.

Common Lisp also has macros like TRACE, which allow, well, tracing and untracing of functions with one call, like this (I think I've got the format wrong, but that's hardly important):

Code: [Select]

> (trace foo)
FOO
> (foo 3)
: (FOO 3)
  : (FOO 2)
    : (FOO 1)
    -> 0
  -> 1
-> 2
Common Lisp also has very sophisticated error handling facilities (not only throw and catch but also so-called "restarts", which provide a way of jumping back into the context where the error happened, instead of being stuck with unwound stack of where the catch happened) and documentation strings (which are basically comments, only that they're associated with the function/variable being defined) which can be accessed without looking into the code, so you can check what a certain function does if you know only its name, without needing to search for where it is defined.
Then there are type annotations and probably many more features I forgot. Not to speak how it might be a better practice to write a macro encapsulating an unusual idea so it becomes easily readable than to comment it. The macro shouldn't be documented with a comment, but a documentation string and how it works can be checked with MACROEXPAND in the REPL.

The remaining cases where comments are actually useful are sparse.

One way to prevent comment rot would be to tie comments to specific code lines. I don't know, maybe a program that goes over a source file, making checksums for code and accompanying comments (how would you detect which part of the code a given comment was for? In Common Lisp you'd count leading ';'s and associate with the appropriate source subtree) and then you can check afterwards whether the checksum of the code changes without the comment checksum changing, too.