Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

“My Code is Self-Documenting”

ericholscher.com

Post reply on HN
Print view View original

41–50 of 100 posts

Re: “My Code is Self-Documenting”

#41

Post by lisivka »

kyberias wrote: post #34

From my experience there is a correlation between the amount of code comments and defects in the code. The more I see comments in the code base of a module, the more likely it doesn't have any (unit) tests and the more it has defects. Yet this may just indicate that the code is complex and therefore required comments and contains bugs. In any case, high comment density is a code smell.

LOL. Comments are not a part of the code. Good comments adds to readability, bad commenting style (e.g. enterprise style comments for everything) affects readability. Comments cannot add bugs to code.

What you think about spaces?

Re: “My Code is Self-Documenting”

#42

Post by Fomite »

kyberias wrote: post #11

Usually the people who cannot write good code love to write comments because they somehow feel it makes the code better. But they cannot write good comments either. Then everything is horrible. Code is really complex and hard to understand and the comments just make it worse. They might be out of sync or just erroneous. I'm witnessing this currently with the code base I'm maintaining.

All people who write bad code write bad comments = / = All people who write good code write good comments/don't need them.

Re: “My Code is Self-Documenting”

#43

Post by sqeaky »

mpweiher wrote: post #23
macintux wrote: post #9

Earlier quoted context omitted.

The danger of stale comments is, I feel, overblown. First, other developers know that comments can grow stale, so they're unlikely to treat them as sacrosanct, although I admit to falling into that trap. More importantly, most of the types of comments that Eric recommends can drift out of sync with the code and still be useful. Why is this code here? What happened previously that is no longer in the code? What tradeo…

> The danger of stale comments is, I feel, overblown. Yes, because they should be, and are, largely ignored. Of course, deleting them is better than ignoring and not having them in the first place is better than deleting.

What about comments that actually help and are accurate, is there no value to that?

Re: “My Code is Self-Documenting”

#44

Post by davrosthedalek »

kyberias wrote: post #11

Usually the people who cannot write good code love to write comments because they somehow feel it makes the code better. But they cannot write good comments either. Then everything is horrible. Code is really complex and hard to understand and the comments just make it worse. They might be out of sync or just erroneous. I'm witnessing this currently with the code base I'm maintaining.

I often work with code bases developed in academic circles. I.e. written by non-c.s. students. Of course they are not experienced programmers, how can they be, it's often their first real software work. There is no professional code review, the code is sometimes beyond ugly, fragile. Bugs get fixed by the next generation... I just ignore all comments. Again, it's not their fault, it is a given just from the situation. But in this situation, it's much better to teach them to write readable code first. And not to trust any comment already in the code.

Re: “My Code is Self-Documenting”

#45

Post by yxhuvud »

fooey wrote: post #28
derefr wrote: post #13

> Explaining previous approaches that didn’t work; explaining trade offs in the current implementation; marking possible improvements (TODOs) in the code; anything else you’d like to communicate with someone reading or developing the code To me, those are the functions of commit messages , not code comments. Of course, a "proper" IDE (and I don't know of any) would give you the context of the commit messages "impingi…

if you're looking at commit messages to figure out a piece of code, you're probably having a very bad day

Eh, that depends totally on the development culture. I do it all the time. Getting the history over time for a specific region is extremely nice when a piece of code is to be understood.

For the emacs users: vc-region-history is the best part of emacs 25. I totally consider it nice enough to motivate people to compile 25 by yourself if your distro doesn't provide it yet.

Re: “My Code is Self-Documenting”

#47

Post by lisivka »

Fomite wrote: post #42
kyberias wrote: post #11

Usually the people who cannot write good code love to write comments because they somehow feel it makes the code better. But they cannot write good comments either. Then everything is horrible. Code is really complex and hard to understand and the comments just make it worse. They might be out of sync or just erroneous. I'm witnessing this currently with the code base I'm maintaining.

All people who write bad code write bad comments = / = All people who write good code write good comments/don't need them.

Yeah, «why you need comments? just read the code» (c) Brainfuck developers.

Re: “My Code is Self-Documenting”

#48

Post by BigJeffeRonaldo »

vinceguidry wrote: post #26
BigJeffeRonaldo wrote: post #22

Earlier quoted context omitted.

It's a matter of incentives. Business folks don't care about comments unless they have a dev background. Your options are then to focus on the incentives present in the situation, or materially harm your own life and well-being by working extra hours to make up for your management's inability to manage.

I hate this excuse. It seems like every lazy habit of programmers gets pushed onto the "business folks". Just because business folks don't know how to value certain developer practices doesn't let you off the hook. Just do what you have to do and if it takes longer because you had to learn how to do it, then it takes longer. Let the business folks tell you when it's taking too long to deliver features.

But it does. It depends on the organization, but there are groups where chugging coffee, talking a lot, and pumping out dozens of half-working features by coding like a drunk cowboy will get you promoted and recognized as a team player, while pushing back to take time and do things right will have you reprimanded. Many such cases out there.

Re: “My Code is Self-Documenting”

#49

Post by kyberias »

Fomite wrote: post #42
kyberias wrote: post #11

Usually the people who cannot write good code love to write comments because they somehow feel it makes the code better. But they cannot write good comments either. Then everything is horrible. Code is really complex and hard to understand and the comments just make it worse. They might be out of sync or just erroneous. I'm witnessing this currently with the code base I'm maintaining.

All people who write bad code write bad comments = / = All people who write good code write good comments/don't need them.

Well, the point is that people who write good, clean code don't need to comment their code extensively. They don't need to continuously explain why they did some horrible hack or some trivialities because their code is well structured and very easy to understand based on other good software development practices. They don't write the requirements of their functions as code comments, rather they write unit tests that document the requirements etc.

Re: “My Code is Self-Documenting”

#50

Post by lisivka »

sparky_z wrote: post #27
joekrill wrote: post #5

Earlier quoted context omitted.

I hear this all the time as to why comments are "bad" (and I'm not suggesting that's what _you_ are saying, btw). Comments need to be kept up-to-date with code changes. The same way unit tests are kept up-to-date, and everything else around your code is. Comments are no exception.

The thing is, if somebody forgets to update a unit test, it immediately becomes obvious. If somebody forgets to update a comment, it's very easy for no-one to notice until it's much too late. There's no way to automate that check. In terms of developer resources, the act of doing updating the comments is cheap, but the act of making sure it gets done (in a systematic way) is comparatively expensive.

To miss comments in the code, developer must be blind. Maybe you are telling us about sad story of external documentation?
Post reply on HN