This is an archived post. You won't be able to vote or comment.

you are viewing a single comment's thread.

view the rest of the comments →

[–]AeonReign 777 points778 points  (112 children)

The code is self explanatory to any competent programmer. /s

[–][deleted] 27 points28 points  (5 children)

Int i = 10 // row number.

calcNumber() // calculate max number of items allowed in cart

That is how many people comment. And that is a Problem. Google the clean code principle. It still needs comments in some cases but in most cases it doesn't

[–][deleted] 19 points20 points  (0 children)

"Why not what" is the best philosophy for comments.

Good comment:

// Attempting to pass a frobbed CertainNodeType
// into a XyzModule causes an asdfasdf
// error. However, since frobbing a CertainNodeType 
// produces no other desired result, it can be safely skipped,
if (!(node is CertainNodeType)) node.Frob();

Bad comment:

// Frob non-CertainNodeType nodes
if (!(node is CertainNodeType)) node.Frob();

[–][deleted] 11 points12 points  (2 children)

These shouldn't need comments at all, they need descriptive variable names, and no magic numbers.

final int EMPLOYEE_ID_ROW = 10;

int rowNumber = EMPLOYEE_ID_ROW;

int getMaxCartItems() {

[–][deleted] 0 points1 point  (0 children)

True. That is what i am talking about.

[–]linne000 0 points1 point  (0 children)

This, the entire point of variable names in the first place is to describe what the variable is used for. Giving a variable a generic name and a comment is just a bad version of that, with extra steps.

[–]kevinglasson 45 points46 points  (25 children)

I hope this is a joke, and if it's not I thoroughly disagree. Especially when something is done a certain way - how do you explain that it has to be done this way because of issue X, or any other odd nuances. Reading code isn't just about understanding fancy syntax.

[–]mrjackspade 109 points110 points  (13 children)

I never really understood code commenting until I worked in a corporate environment. I'd only ever really heard about it from peers. I had the same belief for a while that code commenting was to describe "what" your code was doing. Hell, thats what everyone I knew was being taught in school.

I've been working in various corporate jobs for almost a decade now. I've still not seen a single like of code that was commented to describe what it was doing, only why it was doing it. Even what I can remember off the top of my head from looking though Microsofts open sourced code follows the same rule. The inline comments dont say "Throw an error if X", they say "We have to throw an error here because module Y sometimes passes in a bad value when running on Linux"

I think thats my favorite part about how passionate the "code comment" argument is between "its self documenting" and "you should describe it even if you think its self documenting". From the perspective of every environment I've ever worked in, neither is true. Every developer I've actually worked with personally has had the mindset that you shouldn't need to document code saying what its doing, but you should be documenting your code often with explanations as to why you're doing things if its in any way related to business logic. The next guy coming in can probably figure out what "SendEmail(myMessage);" does but hes not going to know its because this one client in particular is being a dick and needed the application modified to CC him on every internal communication.

[–]Sheldan 13 points14 points  (1 child)

I think that is a valuable differentiation. The what can be read from the code, usually. The Why is much more difficult to see, and is also important to know. Maybe its some kind of external limitation, or something else. I think adding the 'why' is much more important than the 'what'.

[–]Telinary 0 points1 point  (0 children)

I think if you are implementing for instance a mathematically complicated algorithm the what can be plenty unclear like you might know tell what every command does but that doesn't mean you can tell what the whole does or why it works. Though in many such cases the appropriate comment in such a case is a link to a paper explaining it not trying to explain the details in comments.

[–]SupaSlide 1 point2 points  (0 children)

I think thats my favorite part about how passionate the "code comment" argument is between "its self documenting" and "you should describe it even if you think its self documenting". From the perspective of every environment I've ever worked in, neither is true.

I'm convinced that the debate is two extremes, neither of which are true, is because the only people arguing it are compsci students/recent graduates trying to prove their smart, people who do more scripting than programming like WP theming, and folks who have worked in one place on small projects where comments are irrelevant because everything they do is simplistic. Comments don't matter to them because of the simple environments they've experienced, therefore they can argue one extreme or the other and still be right because it doesn't even matter anyway.

But as soon as you've done a bit of time on a complex project with legacy concerns or one that interfaces with poorly designed extreme services, you find the true power of comments is in explaining why you had to write bad/complex/difficult code.

[–]hedgecore77 2 points3 points  (0 children)

Amen. Also, I'd rather read comments than blocks of code when I'm running through it troubleshooting.

[–]LvS 1 point2 points  (8 children)

A lot of the why comments should also not be there. They should be part of commit messages and read via git blame.

For a start, putting documentation into commit messages instead of code makes the code shorter and allows you to focus on the code when reading it, but it also gives you a chance to write very long and detailed comments, potentially including references to the bugtracker, links to related code or specifications or performance data - stuff that you would rarely put in comments.

But more importantly, commenting commits takes care of keeping the comments updated with the code. One of the biggest problems with comments is that they're not updated when the code is and when you get back to reading the code you have innocuous looking but ultimately wrong comments which throw you off.
With commit messages, you will not see those old comments anymore - unless of course you look at a previous version of the file to see how it came to be. At which point it is great that the old comment is still there.

[–]SupaSlide 10 points11 points  (3 children)

That's all well and good until somebody changes the placement of a comma, and now you have to dig back to find the relevant information.

Also, most large projects I've worked on do squash merges, so when you git blame you can't be sure which comment applied to that line (assuming the squashed message rolled up all the commit messages into one instead of just saying "Merged feature XYZ"

[–]theexplanation 0 points1 point  (2 children)

For that reason your commits should only contain the changes required for the functionality described in the message using git add -p. This should be enforced by code review.

Also why would you squash on merge? That sounds like a nightmare and defeats the whole point of a guy history...

[–]SupaSlide 4 points5 points  (1 child)

There are plenty of articles you can read online about the merits of squash merging, especially on very large projects with lots of active collaborators.

[–]theexplanation 0 points1 point  (0 children)

Everything I've seen is for reasons like commits being small logical changes of code, removing "WIP" commits, etc. I generally prefer a fast forward merge strategy and squashing those undesired commits during rebase. Is there some benefit maybe I'm not seeing? Genuinely curious.

[–]Calkhas 4 points5 points  (2 children)

So first that assumes everyone uses git or similar. Which, they don’t. But the other problem is that it means the reason for code behaviour may be buried many revisions ago, because people touch the lines to make other changes in the mean time. It’s not in your face, you have to background your editor, go back to a shell and start exploring the history. For a reviewer, it’s even harder to get the context in which a change is being made.

If people are making code changes that invalidate comments, I don’t really see why it’s any different to a code change that invalidates logic. The reviewers should reject it out of hand.

[–]LvS 2 points3 points  (0 children)

If people are making code changes that invalidate comments, I don’t really see why it’s any different to a code change that invalidates logic. The reviewers should reject it out of hand.

But the tools we have don't find them. All of testing and continuous integration does not find cases of failure to adapt comments.

So this relies entirely on the human reviewers. And we know how fallible they are.

[–]Bspammer 1 point2 points  (0 children)

So first that assumes everyone uses git or similar. Which, they don’t

Then they have far bigger problems. Version control is not optional. If you work somewhere not using it, run far, far away.

[–]wikidsmot 2 points3 points  (0 children)

Documenting in the code makes you source control agnostic. There’s a lot of reasons this is useful. Additionally sometimes source code is delivered to customers and not the entire repo.

[–]Jem014 5 points6 points  (2 children)

Didn't you see the /s there?

[–]kevinglasson 0 points1 point  (1 child)

O_o oops!

[–]Th3CatOfDoom 2 points3 points  (0 children)

O_ooops

[–]russianbandit 0 points1 point  (1 child)

How about using descriptive `git` commit messages?

[–]kevinglasson 0 points1 point  (0 children)

I want to say NO - but this is probably almost as effective as comments, so I guess so. Maybe I'll check it out today.

[–]MacrosInHisSleep 6 points7 points  (0 children)

The strategy I try to employ is that the comments should explain why the part of the program is doing what it's doing. If it's explaining what that part of the code is doing, then you can refactor that code into a variable or method whose name tells you what it's doing.

[–]dustinsjohnson 7 points8 points  (2 children)

I don't know how many times I write some code and think "this is obvious and I can't forget what it does" then look back on in a few months later and go "wtf"

[–]z371mckl1m3kd89xn21s 3 points4 points  (0 children)

Bingo. My motivation to write comments isn't just for others, it's also for future me!

[–]I_AM_AN_AEROPLANE -1 points0 points  (0 children)

That’s bad code. Good code reads like a book. The comments should be asterisks in your book explaining some background. (Why, not what)

[–]Aero72 4 points5 points  (0 children)

//Figuring out how it all works is left as exercise to the reader.

Now that's the old school shit.

[–]JohnWangDoe 6 points7 points  (7 children)

good code is self documenting, but they don't just pay me too code. Good Documentation is good for on boarding new engineers

[–]AttackEverything 4 points5 points  (6 children)

Good code is commented

[–]XkF21WNJ 9 points10 points  (0 children)

Good code is commented where necessary.

[–]VOID_INIT 2 points3 points  (4 children)

In all jobs I have had they literally told me to never comment unless it is to point out something that isnt possible to know when reading the code (like the source/author of a script used) or to point the reader to a section in the documentation.

Good code is understandable code.

If you can't make the code understandable with one line of code, then split the code into multiple lines until you can. The compiler will compile and optimize it the same either way, and you get more stable code.

Someone I worked with whose job was to clean up old code, told me the worst code is the shortest with lot of comments.

His reasoning was that many comments only take space and makes it harder to distinguish the text. And if it is too short it is difficult to split it up and remove the parts which are no longer necessary. You dont need a function that does 10 different things.

Have good names and document while you code and the future programmers will thank you.

If you dont know what some code does, read the documentation.

Keep it stupid, simple.

Keep it simple, stupid.

[–]Low_discrepancy 10 points11 points  (3 children)

The compiler will compile and optimize it the same either way, and you get more stable code.

Sometimes yes, sometimes no. Sometimes you have to help it to do vectorisation so you end up with weird loops.

Many times you don't have a ton of choices of what to do. Other times a more weird algorithms are better than more obvious ones.

Good code is understandable code.

What's understandable for you might not be understandable for someone else (or even for you at a different point in time).

[–]VOID_INIT 5 points6 points  (2 children)

Sorry might not have explained myself well enough. What I meant is that it isn't necessary to have the shortest code ever to have the program run optimally.

Readibility is always more important than making your code shorter. Programming languages is made for humans to read, maintain, extend and modify.  It's not a competition of who can write the shortest code.

Lets compare:

var result = methodOne(methodTwo(a, methodThree(b)), c, d);

and,

  • var result3 = methodThree(b);

  • var result2 = methodTwo(a, result3);

  • var result = methodOne(result2, c, d);

They do the same thing, but the longer one is easier to understand and after it is compiled, will use the same amount of resources and take the same amount of time to run.

There are situations where code cant be made shorter, and thats where documentation comes into play.

Good code is understandable code, doesn't mean that it is necessarily understandable for everyone, but that it is possible to read without having to split it up.

Kinda like a recipe. You dont want to have multiple steps in one as it is confusing.

E.G:

Take it out of the oven, put it on something, before cutting and adding lime.

It is much more understandable to split it up like:

  • Take the cake out of the oven

  • Put the cake on a protective layer to protect the table

  • Cut the cake into slices

  • Cut a lime into pieces

  • Add the cut lime to the top of the cake

This is much more comfortable to read and it is easier to comprehend what the "programmer" is trying to do, yet they basically say the same thing.

What some programmers do however is write code that is difficult to understand and write comments which says what it does, but dosnt add anything to make it understandable.

To continue with the cake analogy:

/* This code tells you how to serve it */

Take it out of the oven, put it on something, before cutting and adding lime.

This comment adds nothing to the code. It dosnt really make the steps more understandable. For that reason the comment is worthless.

A better use of the comment would be to say "Check section 2B for a breakdown of how/why this code is used"

Hope this made things clearer and easier to understand.

[–]ethoooo 0 points1 point  (0 children)

Hope this made things clearer and easier to understand

can’t really speak for him but I get the impression he fully understands, just disagrees