Live data from Hacker News

Software Engineering at Google

books.google.com

71–73 of 73 posts

Re: Software Engineering at Google

#71

Earlier quoted context omitted.

> Seriously, unless a code comment is illegible or it’s being compiled into user-facing docs, it’s absolutely useless to leave something like “nit: it’s TCP, not tcp”. I think you're describing style errors, not grammar errors. For example, the Google style guide says that (certain) comments should be complete sentences. Asking people to use good grammar (and capitalize/punctuate) those sentences as though they were…

> I think you're describing style errors, not grammar errors. The entire thread (not started by me) is about nit-picking punctuation and now you’re trying to explain to me that I’m describing style errors. So what? It’s useless feedback regardless of which chapter in the Holy Google Docs covers it. > Asking people to use good grammar (and capitalize/punctuate) those sentences as though they were documentation (becaus…

My experience differs. Consistent and well formed prose in docstrings and comments absolutely helps reason about unfamiliar code. Nitpicking for good formatting, spelling, and grammar is valuable in code comments just the same as in documentation or any other form of technical writing.

If the comments aren't important enough to spend care and thought on, they should be deleted.

> If it has a meaningful impact on the ability to read it, it’s not a nitpick.

This is boring semantics. Given what you describe as nitpicks, we draw the line of meaningful impact on readability in different places. So I'm claiming that some of the things you describe as nitpicks in fact aren't.

Re: Software Engineering at Google

#73

This is probably a very dangerous book that a bunch of monkeys will make into a dogma. On the other hand, this one from Google is awesome http://streamingsystems.net/

Did you find a copy with well formatted diagrams?

I have printed version. The diagrams are ok, but seem to be on wrong pages, too much flipping back and forth
Post reply on HN