search

ainzzorl / goodcode

A curated collection of annotated code examples from prominent open-source projects
https://codecatalog.org
Creative Commons Attribution 4.0 International
198 stars 8 forks source link

2021/09/04/well-documented-code #58

Open utterances-bot opened 3 years ago

utterances-bot commented 3 years ago

Writing Well-Documented Code - Learn from Examples - Code Catalog

Writing Well-Documented Code - Learn from Examples

https://codecatalog.org/2021/09/04/well-documented-code.html

nyanpasu64 commented 3 years ago

Personally I feel the AWS CLI isn't obvious that the comment contains "the expected format of the input in the beginning of most parsing methods". It looks almost like outdated code commented out, and when reading the code alone (before reading your commentary) I didn't understand what the comment meant. Perhaps the comments would do better with English explanations like "This function parses the pattern:" once per function, or at the top of the file, but I'm not sure if it's a net improvement or not.

I've seen a similar issue in MUNT (link), where the MT-32 hardware emulation functions contain commented-out valid C++ involving floating-point operations, followed by fixed-point/integer code involving the same input and output names. I didn't know that the commented-out C code represented an exact formula that the integer code (and the hardware) was seeking to approximate, and I wasn't sure they even matched approximately until I traced the integer code to convince myself.