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…
Bill is not replaceable
Bill is a liability.
But an irreplaceable liability.
x += 1; // Increases x by one…Years later
x += config.increment; // Increases x by one""" config.yaml increment: -2 """// 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 instructionWait 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.
That’s what it used to do.
But it was a bug, and the code has been fixed.
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.
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.
Wow the comments here sounds like you’re all a bunch of antisocial nightmares to deal with in rL.
“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”
`//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?
