2021/09/04/well-documented-code

[utterances-bot]

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]

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.