Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Comment your damn code

tech.collectedit.com

Post reply on HN
Print view View original

31–40 of 68 posts

Re: Comment your damn code

#31

Post by jrabone »

Toshio wrote: post #7

Well, I disagree. Test-drive your damn code. The difference in positive impact will be a few orders of magnitude.

Until someone comes to do major rework and your tests take ten times longer to change than the code. It happens - a lot. Badly structured tests are worse than no tests to the extent that it's often cheaper to throw the lot away and write new tests - turning what should have been a simple "change the class hierarchy without changing the public interface" into "oh god every single test relied on the detail of the class hierarchy". No, they SHOULDN'T have. But they DID. And I get to fix it. Again. A particular anti-pattern I am observing right now is the "immutable interface, mutable implementation" approach. Every single test in 6 different sub-projects appears to want to create "special snowflakes" for testing, but was written to mutate an implementation which no longer exists. Days of extra work needed to figure out what the intent of the test was (no comments, because tests are self documenting, right? Sure they are.) and then re-write it using builder interfaces in the hope that this will save some poor sod (probably me) the trouble the second/third/fourth rewrite.

Be a better damn developer. Tests don't deserve cut and paste hell any more than your actual production does.

Re: Comment your damn code

#32

Post by khebbie »

darrencauthon wrote: post #24

"Every 3 to 7 lines of code you'll find some amount of editorializing. Maybe every few hundred lines you'll find a good joke too." I think there's the issue. In applications I write, every 3-7 lines of code is refactored into a method that is named exactly what it does, and every few hundred lines of code (usually much less) is in a separate file and class named on what he does. Broken out like that, there's not many…

Yes excactly!!!

Re: Comment your damn code

#34

Post by ygra »

augustl wrote: post #18

There's usually a large amount of comments and metadata relating to code that isn't present in the source files themselves, but in an external database: git blame path/to/file.txt I think this is one of the most underused tools in software development! I wish more editors had features like "show me the history of this class/function" etc.

Strange. If I do this here all I get is “Empty commit message” for every change.

Re: Comment your damn code

#35

Post by sparkie »

khebbie wrote: post #30
larsmak wrote: post #13

I'm against commenting code, with two exceptions: - You're implementing something complex (like an algorithm) - You're implementing something stupid (typically a workaround for something that could not be done in a more elegant way, and you want to explain why it can't be refactored) If the code is well written it is also self explanatory. This can be done by structuring / formatting the code well, into methods, clas…

Agree completely C# 11 years of experience

There's an huge requirement for comments in C# that isn't needed in java - that of describing what exceptions a method may throw. This is probably also the place where comments are ignored most of the time too - I literally cannot count the number of times I've seen programmers failing to catch obvious exceptions, even in the framework libraries.

Re: Comment your damn code

#37

Post by ygra »

sparkie wrote: post #35
khebbie wrote: post #30

Earlier quoted context omitted.

Agree completely C# 11 years of experience

There's an huge requirement for comments in C# that isn't needed in java - that of describing what exceptions a method may throw. This is probably also the place where comments are ignored most of the time too - I literally cannot count the number of times I've seen programmers failing to catch obvious exceptions, even in the framework libraries.

The framework documentation is very good in that regard, though.

Re: Comment your damn code

#38

Post by olavk »

lmm wrote: post #2

Nope. You need to comment every nonobvious decision, but if you write code the right way then the nonobvious decisions disappear. A well-written method doesn't need explanation, because it obviously couldn't have been written any other way.

    // NOTE: Workaround for a bug in the framework
    // foo will crash if you foo before bar.
    // Here we bar with a null value, which prevents the crash
    bar(NULL);

Re: Comment your damn code

#39

Post by blackysky »

You should comment your code if and only if your algorithms has special pre-conditions and post-conditions otherwise your choice of variables name should make your code speak by itself... exemple of pre condition: your algorithm don't handle non latin word ... exemple of post condition , your algorithm only return a specific format like aa-bb-cc ...

or like my teacher said use your common sense, make your code as clear as possible.. I should understand it without you ...

Re: Comment your damn code

#40

Post by CKKim »

If the author had simply chosen a few examples of good commenting in code and exhibited them, then he wouldn't have had to write this article explaining his point..or would he?
Post reply on HN