3 ms·
Google Developers Don’t Write Their Comments
- onion2k 4y agoCode may come and go! We write them, modify them and sometimes later delete them. But documentation is different — they shouldn’t change no matter what. This is wrong in most cases. Documentation should change as the app changes. In some documentation systems its possible to version the docs nicely, and keep them inline with the application version, but for lots of documentation that we write that's not the case. It's important to go back and edit documentation to add, remove and update sections as the world around the application changes. Documentation that fails to reflect the reality the user is working in is incredibly frustrating. EDIT: To be fair to the author, they actually say as much in the post, but the format of a "call and response" they've chosen doesn't make their intent very clear at all (slightly ironic considering the topic). If you're going to write in a way that refutes the 'parody' points don't put an image in between the point and the refutation.
- kurupt213 4y agoWhy is every website so reader unfriendly now. I don’t want to log in or move to an app
- DogLover_ 4y agoThe example with 'pattern' I really prefer using the variable 'pattern' instead of naming the variable to 'socialSecurityPatterUS'. Variables being too descriptive always felt like a dumbification that don't make the code better on an aggregate level.
- wokkel 4y agoThe developer working on that code 3 years later will love dumb names.
- edflsafoiewq 4y agoHow not to write an article: randomly intersperse paragraphs with "real suggestions", arbitrary pullquotes, miscellaneous blurbs, and unrelated images. Also italicize half of it with no apparent logic.
- james-skemp 4y agoTitle should be "How Google Developers Don't Write Their Comments" As it is I came into it expecting that at Google during a review process (perhaps?) comments are written in the code by reviewers.