this post was submitted on 26 Nov 2023
710 points (89.3% liked)
Programmer Humor
19512 readers
347 users here now
Welcome to Programmer Humor!
This is a place where you can post jokes, memes, humor, etc. related to programming!
For sharing awful code theres also Programming Horror.
Rules
- Keep content in english
- No advertisements
- Posts must be related to programming or programmer topics
founded 1 year ago
MODERATORS
Yeah, but unironic...
If your code needs comments, it's either because it's unnecessarily complex/convoluted, or because there's more thought in it (e.g. complex mathematic operations, or edge-cases etc.). Comments just often don't age well IME, and when people are "forced" to read the (hopefully readable) code, they will more likely understand what is really happening, and the relevant design decisions.
Good video I really recommend: https://www.youtube.com/watch?v=Bf7vDBBOBUA
Yeah, another way I've heard it phrased is comments are for explaining why you did things a certain way, not for explaining what it's doing.
Exactly that! Everyone can See "what" is happening, the code is right there. But the code usually doesn't tell you "why" that is happening - good comments help understand the authors intent and give context, so you don't have to guess.
Good comments should explain the things that are not obvious.
Good comments more than once prevented me from accidentially undoing a fix.
load more comments
(1 replies)
load more comments
(4 replies)
If you're working with others, even simple code benefits from comments explaining what it's intended to do. Sure you can read code and get a good idea of what it seems to do, but you can't be sure that's what it was meant to do, or why it was meant to do that. Having a quick statement from the author enables you to work faster. And if you find a mismatch between the comment and the code, it's a smell that could mean a bug.
And for methods and functions it's particularly helpful to have a description at the top. Many IDEs will pop this up when you're using the method, so you can quickly confirm that it's appropriate for your needs and get your arguments in the right order.
I even comment code for myself because it will save me time when I return to the project months later.
No comments would be fine if you could trust that everyone writes code that does what it's intended to do and you can read code as quickly as you can read English. Maybe I'm a poor coder but I find neither of these is usually true.
Don't get me wrong comments != documentation (e.g. doc-comments above function/method).
I probably was a bit unprecise, as others here summed up well, it's the why that should be commented.
That's like saying a book's synopsis shouldn't exist because you can just read the whole book. Sometimes comments can save you a lot of time and point you in the right direction.
load more comments
(2 replies)
Sounds very theoretical, my experience working on some 40 year old software full of business logic, where customer A got some feature but customer B needs it to work slightly different. Aka something approaching spaghetti.
Regarding old comments I have several times used ~15 year old comments by the original author, close to the actual code to piece together the use of that code, and if I can add my fix there.
In this setting You write comments for yourself, when you in two years need to fix a bug in the new code caused by your old code. And for the next developer that will look at your code decades after you left the company.
Sometimes you, against good practice, comment out a section, with a note why, because you know this will have to be re-enabled in a few months.
Report from the frontlines...
I have such a love-hate relationship with that video. On the whole, I think that video is bad and should be taken down. The creator is arguing against a very specific type of commenting but is harassing comments in all forms. It even addresses as such with a 20 second blurb 2/3 of the way into video distinguishing between "documentation comments" - but doesn't really provide any examples of what a good documentation comment is. Just a blurred mention of "something something Java Doc something something better code leads to better documentation" but doesn't elaborate why.
It's a very devious problem in that I don't feel like any particular claim in the video is wrong, but taken within the context of the average viewer, (I teach intro. comp. sci courses and students LOVE to send this video and similar articles to me for why they shouldn't have to comment their spaghettified monstrosities), and the inconsistent use of comments vs. code duplication vs. documentation, the video seems problematic if not half-baked.
In fairness, it is great advice for someone who has been working in the industry for 15 years and still applies for junior positions within the same company - but I can't imagine that was the target audience for this video. In my experience, anyone who has been programming on a large-ish project for more than 6 months can reach the same conclusions as this video.
load more comments
(1 replies)
This mindset is good, but unfortunately enforces bad programmers to leave their undocumented code in critical places where someone eventually has to figure out what the hell they were doing or refactor the whole damn thing because they got promoted to middle-management and can’t remember why they even wrote it.
load more comments
(7 replies)
Code comments are useful for browsing a script and understanding it at a glance. I shouldn't have to scroll up and down across 700 lines of code to figure out what's happening. It's especially useful with intellisense, since I can just hover over a function and get a tooltip showing the comment, explaining what it does. It also helps when using functions imported from other files, since it'll populate the comment showing me what parameters are needed and what each should be. Comments save time, and time is valuable.
I’ve seen code that look like this:
int delay = 15 * 60; // 10 minutes
Even if the comment was on the same line someone forgot to update it. People just ignore comments.
Better solution is to write (in C#):
TimeSpan delay = TimeSpan.FromMinutes(15)
Much more obvious what the code actually means.
A better comment would be delay in seconds as that is the one thing not obvious from glancing at the code.
Or just name the variable delaySeconds if you really want to store it as an int. Bonus is that every use of the variable perfectly communicates what it is.
load more comments
(4 replies)
load more comments
(11 replies)
x += 1; // Increases x by one
// increase the dynamically allocated memory space of a word sized integer stored at the memory address represented by the symbol "x" by the integer 1 and terminate the instruction
Wait why is it dynamically allocated and why are you increasing the memory. Something is very wrong here
Why the heck does it need to be dynamically allocated? Just put that puppy on the stack.
load more comments
(1 replies)
...Years later
x += config.increment; // Increases x by one
"""
config.yaml
increment: -2
"""
x++; // Move X position forward by one
There, I made that kind of comment more useful!
x++; // Set x to the incrementation of the value of x
Much better.
load more comments
(1 replies)
Bill is not replaceable
I strive to replace bill. I only work on undocumented code from 3rd parties.
load more comments
(1 replies)
load more comments
(1 replies)
Bill does not work with other people.
More like, other people won't work with Bill.
“Nobody wants to work anymore” -bad manager mating call.
"I'll just be extremely precise with my variable names. Then everyone will know exactly what everything does!"
Uses variable names like "INTEGER" and "STRING"
I'll be that person who makes an catch block for something as simple as double n = 2+5.
code: return isPersonAStudent()
manager in code review: WHY NO DOCUMENTATION!!??
load more comments
(1 replies)
Bill should have his own special branch, Bills Branch
Comments don't describe the code. They describe the decision to use this business logic.
If you stick to good engineering practices, like small methods/functions, decoupling, and having testable code, you don't often need many comments to show what your code does. I always recommend a method signature, though, because you can save a few seconds by just saying that a block of code does, rather than me needing to read exactly how you turned one dict into another dict...
load more comments
(2 replies)
`//Get CustomerInfo from CustomerRepository by Customer ID or else throw an CustomerNotFoundException
public CustomerInfo getById(String customerId) {
return customerRepository.getById(customerId).orElseThrow(new CustomerNotFoundException());
}`
This is the kind of pointless comment I see in my codebase all the time. Best I can tell, a couple of my coworkers like to plan out their code using comments, then backfill in the actual executable code. That's fine, but they leave the comments in when they add no value.
` public static LocalDate parseEndDateFromString(String dateString) {
try {
String[] split = dateString.split("-");
//In order to get the last day of the desired month, we go to the first day of the next month, account for rollover, then subtract one day
int month = Integer.parseInt(split[0]) == 12 ? 1 : Integer.parseInt(split[0]) + 1;
return LocalDate.of(Integer.parseInt(split[1]), month, 1).minusDays(1);
} catch (Exception e) {
throw new RuntimeException("Invalid date format - must be MM-YYYY");
}
}`
Stuff like this, otoh, is where comments are useful. The required format is obvious from the error message, the param and return from the method signature, the only part that requires a comment is the fiddly logic of accounting for the edge case where month == 12 and the rationale behind how we determine the last day of the month. As a rule, comments are for why something is being done, if it's not obvious, and for magic numbers. Code should tell you what code does.
edit: can anyone spot the bug that I introduced with that parseEndDateFromString() method?
This is what I call a 'pro grammer move.'
Wow the comments here sounds like you’re all a bunch of antisocial nightmares to deal with in rL.
load more comments
(1 replies)
Code should be self documenting.
But you should also comment it, things obvious to you aren't obvious to even future you.
General rule of thumb: Comments say why is it here, not what it does. Code itself should describe what it does.
But then you write code in the real world and find out that you have to write some ass backwards code every other day because of deadlines, backwards compatibility or whatever, and suddenly you realize that despite your best efforts, code cannot always be self documenting.
Source: me.
load more comments
(2 replies)
view more: next ›