Hacker News new | ask | show | jobs
by dsfyu404ed 2902 days ago
I'd take C code sprinkled with assembly or bash one-liners optimized for fewest number of characters over Python, JS or PHP spaghetti that's partially documented by someone who can not write proper sentences in the whatever language they're writing documentation in. If you can't be sure your documentation actually reflects what the code does and how it does it then just don't document it or at least throw a disclaimer in the docs. This is even more important is "the docs" are your comments in the source and/or commit messages.

Edit: And why exactly is this opinion unacceptable? Being able to communicate what you're done (and hopefully why you did it) is an essential part of writing software that will be worked on and/or used by other people. Code that takes just as long to figure out how to use as it does to create from scratch is as good as no code.

1 comments

Yes! Writing code that documents itself is the recommended practice when practical. It’s inexpensive relative to other forms of documentation, and it documents precisely what the code does, since it is the code. (And please don’t read this as “never write any other documentation”. This is just the easiest way to get some documentation.)