4 ms·
I don't think I would not extend a job offer for lack of a docstring, especially given how trivial most of these functions are paired with their self-explanator
by emidln 8y ago
I don't think I would not extend a job offer for lack of a docstring, especially given how trivial most of these functions are paired with their self-explanatory names. I'd actually rather a namespace docstring explaining intended scope and api than function docstring for trivial functions. I've found that function schemas/specs and reasonable names eliminate 90% of docstring material. Whether the remaining 10% is worth the string above and beyond the fn name is a case by case deal.
Comments are fine when the code is doing something unexpected or that is very terse. In other scenarios, comments are just a land mine to be armed when the code changes and the comment isn't perfectly updated. Bugs largely come from developer expectations being broken (mostly by one of: misunderstanding data shape, some API detail, some language feature, or miscommunication on the feature with the owner) and stale comments are a contributor to this which can be avoided in many cases.