“My Code is Self-Documenting”

Re:“My Code is Self-Documenting” by sparky_z on Friday January 27, 2017 @04:10PM (#13502691)

The thing is, if somebody forgets to update a unit test, it immediately becomes obvious. If somebody forgets to update a comment, it's very easy for no-one to notice until it's much too late. There's no way to automate that check.

In terms of developer resources, the act of doing updating the comments is cheap, but the act of making sure it gets done (in a systematic way) is comparatively expensive.

[ Parent | on HN ]

Re:“My Code is Self-Documenting” by x0x0 on Friday January 27, 2017 @05:07PM (#13503131)

So add comments to your code review process. This really isn't hard.

For example: python functions shall have a docstring unless trivial. For external api functions on a class, there must be at least one example. etc etc. Plus, this makes working in ipython really nice!

[ Parent | on HN ]

Re:“My Code is Self-Documenting” by emodendroket on Friday January 27, 2017 @08:39PM (#13504286)

I usually apply something like this except only for public methods; I figure if you're digging around the private methods you probably need to look closely anyways.

[ Parent | on HN ]

Re:“My Code is Self-Documenting” by joekrill on Friday January 27, 2017 @04:43PM (#13502951)

But it's not immediately obvious if someone changes something that isn't covered by a unit test. Or forgets to create a unit test. Does that mean we should just abandon writing unit tests altogether?

You could always use a tool like Danger (http://danger.systems/) to inspect your code and warn you when code has been updated, but comments nearby have not been.

[ Parent | on HN ]

Re:“My Code is Self-Documenting” by MaulingMonkey on Saturday January 28, 2017 @06:49PM (#13510458)

> But it's not immediately obvious if someone changes something that isn't covered by a unit test. Or forgets to create a unit test.

This is what code coverage analysis/metrics try to address.

> You could always use a tool like Danger (http://danger.systems/) to inspect your code and warn you when code has been updated, but comments nearby have not been.

I'd worry about tuning out said warnings after too many false positives. Comments regular enough to not generate too many false positives can generally be turned into real syntax of some description.

[ Parent | on HN ]

Re:“My Code is Self-Documenting” by lisivka on Friday January 27, 2017 @04:38PM (#13502913)

To miss comments in the code, developer must be blind. Maybe you are telling us about sad story of external documentation?

[ Parent | on HN ]

Re:“My Code is Self-Documenting” by lgas on Friday January 27, 2017 @04:51PM (#13503016)

This isn't true, especially when you're dealing with legacy code that is overcommented. Your brain will learn to tune them out.

[ Parent | on HN ]