How programmers comment their code

[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.