Programming Things I Wish I Knew Earlier

theodp writes "Raw intellect ain't always all it's cracked up to be, advises Ted Dziuba in his introduction to Programming Things I Wish I Knew Earlier, so don't be too stubborn to learn the things that can save you from the headaches of over-engineering. Here's some sample how-to-avoid-over-complicating-things advice: 'If Linux can do it, you shouldn't. Don't use Hadoop MapReduce until you have a solid reason why xargs won't solve your problem. Don't implement your own lockservice when Linux's advisory file locking works just fine. Don't do image processing work with PIL unless you have proven that command-line ImageMagick won't do the job. Modern Linux distributions are capable of a lot, and most hard problems are already solved for you. You just need to know where to look.' Any cautionary tips you'd like to share from your own experience?"

Re:Comment your code

[Anonymous Coward]

Put enough comments in your code so that five years from now you (and others) can remember what you indented the code to do

I indented the code to make it readable. That's so obvious I don't need a comment to remind me.

Re:Comment your code

[Anonymous Coward]

"indented the code to do"

So the real question is tabs or spaces?

Re:Comment your code

[Anonymous Coward]

> Remember that comments are not for describing what the code technically does (that is what the code is for), comments are for what the code is intended to do.

Corollary: Never debug comments, only code.

Re:Comment your code

[DMiax]

Put enough comments in your code so that five years from now you (and others) can remember what you indented the code to do.

I know, Python right?

Re:Comment your code

[Anonymous Coward]

It's obvious to you now, but what about in ten years when you realise you should have had the opening brace on the same line as the if statement?

(Now to sit back and watch the fireworks!)

Re:Comment your code

[Korin43]

I don't know. I prefer to comment, just in case:

while 1:
        # Indentation
        dosomething()

Re:Comment your code

[TeknoHog]

Put enough comments in your code so that five years from now you (and others) can remember what you indented the code to do

I indented the code to make it readable. That's so obvious I don't need a comment to remind me.

(pun indented)

Re:Comment your code

[nacturation]

dead comments mislead the person following later into believing a lie a lie that could potentially have major impacts on the software.

// the following code delivers cake to the subject

Re:Lesson #8

[danieltdp]

The reason are two fold:

1) The amount of morons *always* exceeds the amount of experienced and reasonable people

2) Usually, morons don't have a clue that they... well... are morons!

I for one can assure you that I'm NOT a moron :-)

Re:Comment your code

[Anonymous Coward]

// the following code delivers cake to the subject

// the preceding comment is a lie!

// the above comment explains the joke

Re:Lesson #8

[SL Baur]

There's no substitute for a few solid courses in theory and design.

You must be new here. When I started programming, there were only a handful of colleges that had computer programming departments.

You came along late enough that you might have had decent instructors.

And I walked to and from college both ways, uphill, in the snow, barefooted, my first programming class used paper tape, my second programming class used punch cards, yadda yadda yadda.

Now, get off my lawn!

Re:Comment your code

[gringer]

// the following code delivers cake to the subject

// the above comment explains the joke

== changelog ==
* removed redundant comments

Re:Comment your code

[rhyder128k]

The road to hell is paved with good indentions.

Re:One more tip

[dbIII]

C# is already .NET, there has never been any other version.

Java :)

Re:Comment your code

[Greyfox]

/* Don't touch this function unless you REALLY know what you're doing */ Funnily enough the only guy who ever touched it didn't know what he was doing. In the short time he worked there, he did enough damage to the code base that it took 6 months to fix it. Too bad the version control system we were using at the time didn't allow you to simply mass-revert a user. That would have actually saved us a lot of time.

Re:Comment your code

[IICV]

Is there a reason your haystack is a list and not a binary tree?

Clearly, this is why you need comments! Haystacks aren't lists - they're heaps.