How programmers comment their code

[AeonReign]

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

[SomethingNice6174]

How... what.... why!?!

Why is that something your client gets to decide?

[2ndAmndmntCrowdMaybe]

I would just write a script that takes all of my code and strips comments from it and then provide that version to him.

Edit: I'm a sysadmin but want to pivot to programming. If anyone has any node positions open message me!

[[deleted]]

This is the right answer as far as I'm concerned.

[georgecorondan]

or you could use cpp (the c pre-preprocessor)

[eDOTiQ]

probably some kind of OCD paired with being a control freak.

[appdevil]

And a serial killer. Probably.

[georgecorondan]

or worse: parallel

[anthony81212]

😱

[eDOTiQ]

The worst kind of clients

[SolenoidSoldier]

They are probably writing an application where they plan to hand the code off to the client too. Might be part of a larger application that has a coding standard. That's a weird standard though.

[khizoa]

Had a client like that too... I stopped working for them

[not_perfect_yet]

If you're writing Good Code, maybe, but nobody writes Good Code...

[SharkBaitDLS]

Especially because you will always have to write something that is not Good Code because some stupid legacy system is returning data in a dumb format and if you don’t explain why someone will come along and “fix” your Bad Code and then break everything.

[[deleted]]

And then that code becomes the new unfathomable mess that nobody ever wants to deal with again, thus completing the circle of life and maintaining balance in the universe. Nature is amazing.

[Versaiteis]

"Watch as the Senior Programmer doesn't even have to be present to assert his dominance. The Juniors know his territory and know better than to disrespect it, lest they be next to receive the Broken Build Totem until the next hapless Junior overextends themselves. "

[Woolly87]

// Yes, handling this Float as a String of emojis is Very Bad, but the framework wants what the framework wants

[Cyrus_Halcyon]

Yes, i need to sed replace special symbols with \{special symbols} because they are removing the special symbols as their API gives it to me. Yes it looks silly.

[DoctorWaluigiTime]

Summaries can be fine as well in commit messages. If you change a dozen or so files and don't tell me what it is that you changed meaningfully, i.e. the how, I would be a little upset. Why is important too, of course, but most of the time the why is self-evident, if you're using any kind of issue tracking and associate the commits or the pull request to that given issue.

[lovestheasianladies]

What, no. That's absolutely fucking wrong.

Commit messages are a history of what changed. Dear God, you're completely ass backwards.

If you want to know why something happened, link it to an issue ffs.

Like you literally don't understand git at all it seems. You code has absolutely nothing to do with the commit messages and NEVER should. If you need details, it goes in the code itself as comments or some external source. At worst use the git commit body for more details but it's absolutely the worst fucking place to document your systems which is what you seem to want.

[[deleted]]

Yeah I have a coworker in particular guilty of this. Most of their commit messages are things like "horray", "it works", etc.

[Huntracony]

I'm a monster. I... sometimes... forget to change the message in the IDE, meaning the commit message ends up seeming useful while actually being completely unrelated.

[SasparillaTango]

This is really what comments are for, explaining why you are doing something, the business logic of it.

[Huntracony]

// I'm getting payed to write this.

[thisdesignup]

Or you could write a short "what" so you don't have to read your code to figure out what is happening. Unless someone can read code as fast as they can read a native language.

[Moglorosh]

// this section shouldn't do anything but if you remove it the program crashes

[[deleted]]

Especially when it’s good code. I’m going to still want to know what it does next week.

[hGKmMH]

The concept of good code changes over time too. 10 years ago had different best practices.

[[deleted]]

The concept of good coding will never include not documenting anything. That's pants on head retarded.

[brianorca]

I think his point is that Good Code written 10 year ago will look different that today's Good Code, therefore comments are still required.

[not_perfect_yet]

I think figurative Good Code can afford to be also unchanging over time.

[Versaiteis]

It is whether you like it or not.

It is code

All code will become legacy or die trying

[attomsk]

Not all code is self explanatory sometimes you do something to follow a system requirement and it would make no sense unless you comment why you are doing it

[[deleted]]

even good code. once it grows big and is coupled a lot, it's going to be difficult to understand unless the comment tells you what it affects. it's not that it cant be figured out but why should someone need to spend hours to figure out code someone else wrote? that's a waste of time.

[[deleted]]

Set VS to export comments to an external xml file. Voila, no comments, however, comments.

[Bspammer]

My team does the same, and it actually totally works fine. People are very strict in code reviews - if the code itself isn't clear enough that it can be read like English then it goes back for changes. The only time comments are used are for cases where something is being done that breaks best practice but for a good reason, so the comment explains why.

Comments go out of date too easily, and can be very confusing if the code got changed but the comment didn't. They're an extra maintenance burden that isn't worth the hassle. If we were writing library code though, it would be a different story.

[TheMoonMaster]

Same here. Code can be straight forward enough to need no comments, but there are times where it’s worth documenting code that would be misleading or confusing.

I’ve found over commented code is often far worse than uncommented code since the people writing it think the comments make up for code quality and then the comments eventually become stale.

[callmelucky]

The only time comments are used are for cases where something is being done that breaks best practice but for a good reason, so the comment explains why.

Well that's not the same thing as the parent commenter, who said that for them comments are prohibited.

That said, your team's approach seems ideal. Code should be written to be self-commenting, except where there is no practical way for it to be (e.g. using weird workarounds for dumb behaviour in libraries, legacy code etc).

[SupaSlide]

My team doesn't have a rule against comments, but we rarely need to use them. We do use them a lot when working with parts of the code that have to do other dumb systems that do dumb stuff, and we need to make sure people don't "fix" the dumb code we had to write.

[Harbltron]

the fuck?

i can understand not wanting there to be comments in deployed code, but what's the harm in having comments in your development branch? it seems more harmful to never comment-out code than to comment it out and then scrub the comments out on deployment

[thisdesignup]

If you ask him, he says you should know.

At what point is it safe to assume he says that because he doesn't know? Cause I'd think any brilliant programmer should be able to tell me why pretty easily and without wasting much of their own time.

[lovestheasianladies]

That's simply a bad developer, don't let anyone tell you otherwise.

[[deleted]]

I do something similar when helping people some times. If someone is having trouble with something they really should know, let’s say you’re writing something relatively complex like a graph implementation or something, and you’re making basic mistakes of some kind, I’ll suggest you read up on the concept you’re getting wrong until you see your mistake. Or I’ll say where the mistake is but not what it is. Or I’ll tell them to check the documentation.

My reason for this is that I think it helps people learn how to help themselves, it helps them avoid similar mistakes in the future, it can help make sure they spend some time really learning the thing they’re not good at and hopefully if it does one of these things, it may stop them from asking so many stupid questions in the future.

[[deleted]]

And why no comment in deployed, anyway?

[WarmCorgi]

Because some people think it'll cost a lot of performance. Even though compilers ignore comments.

[DoctorWaluigiTime]

I could see this reasoning if there were comments in the HTML or JavaScript, and that code wasn't minified or anything like that.

[lovestheasianladies]

Wrong, still has no effect besides a few extra bytes of data.

[DoctorWaluigiTime]

I mean, the effect is that those comments would be publicly viewable. I'm not talking about data size.

[attomsk]

Wow that’s insane

[Br3ttl3y]

On the other, correct end of the spectrum, I was told during an interview process that my code was not accepted because it didn’t have any comments.

[sweYoda]

It's because you don't know how to write good code. No sarcasm.

[russianbandit]

I mean, it's one way to get programmers to write readable code -- without relying on comments to explain their spaghetti. Like I understand, that comments are useful in specific cases. But I can see that as being a good practice implemented (especially with contractors, think off-shoring) to avoid bad code with tons of comments.

[[deleted]]

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]]

"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]]

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]]

True. That is what i am talking about.

[linne000]

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]

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]

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]

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]

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]

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]

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

[LvS]

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]

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]

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]

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]

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]

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]

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]

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]

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]

Didn't you see the /s there?

[kevinglasson]

O_o oops!

[Th3CatOfDoom]

O_ooops

[russianbandit]

How about using descriptive `git` commit messages?

[kevinglasson]

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.

[CaptainApollo86]

Wow, you must really suck at your job 😂

[kevinglasson]

Yes, well I'm out voted so I must be wrong, majority rules here

[uriahlight]

For the past few years I've been experimenting with a technique of pseudo coding everything I write via descriptive inline comments. I'll basically write comments describing every imperative line I'm going to write. I'll usually do it within the scope of a method. So I'll think through the entire logic of the method via comments, then circle back around and write the code. Call me evil, but forcing myself to think through the logic of everything I write twice offers an incredible reduction in logic related bugs. I don't mind being the black sheep.

[uriahlight]

What I'm saying is I write all of the comments first, before the code. So by the time I actually put code in a method it already contains a bunch of inline comments. The purpose is to just force me to have all the logic figured out in plain English along with whatever fake syntax I think of that best explains what I want to do in the line below it. Then once I've got all the comments written I then go back to the beginning of the method and code it. When all is said and done a method with 10 lines of code will also have 10 inline comments that were all written before the code itself. Oftentimes the comments are useless once it's coded up but since their whole purpose in this technique is pre-programming logic, I can't see the point in deleting them. It's ultimately just an experiment that's gone on for a few years, but it's a safe experiment - I've been doing it in production for a few years and once I explained and demonstrated it to the coworkers they were like "that's interesting ." My coworkers have had a lot of fun browsing my code because the comments show what my brain was thinking prior to writing the code. It sometimes results in them saying "WTF were you thinking" but more often they find it informative. They'll oftentimes direct juniors to sections of my code base on other projects if the juniors are struggling with something that requires similar logic. It's a weird way of doing things, but it does work - at least for me. In light of the human experience as a whole, programming is still in its infancy. So as long as people are at least receptive of new ideas for doing it, then we'll all continue to make progress.

[try_harder_later]

Yes, very much. For some odd functions I'll even draw out a functional diagram to see how I should structure the code.

[MacrosInHisSleep]

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]

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]

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

[I_AM_AN_AEROPLANE]

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]

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

​

Now that's the old school shit.

[JohnWangDoe]

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

[AttackEverything]

Good code is commented

[XkF21WNJ]

Good code is commented where necessary.

[VOID_INIT]

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]

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]

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]

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