4 ms·

Anyone who writes Lisp without taking a moment to add a docstring to every definition would never get a job offer from me. (Not to mention comments as appropria

Anyone who writes Lisp without taking a moment to add a docstring to every definition would never get a job offer from me. (Not to mention comments as appropriate.)

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.
zonotope 8y ago
Clear and descriptive function names, concise and non-clever code, and a judicious use of well-named and concise helper functions are all way more valuable than docstrings. IMHO docstrings should be used as a last resort if the problem domain is truly complex enough to warrant it. Docstrings for trivial, well-named functions just get in the way, and if you feel the need to add a docstring to a complex function just after you've defined it, then I think that might be a hint that you should refactor the code to make it more clear and readable instead. An ns docstring that describes the intent of the api and docstrings for the major public interface functions are a good idea, but a blanket "docstring for every function" rule is a crutch to make up for unreadable, poorly-written code.
jogjayr 8y ago
If you have to write a comment to explain every definition, you've failed to make the code sufficiently readable and simple to understand IMHO. Code-level comments can become outdated without eagle-eyed code-reviewers. The code itself can never lie. Comments are a useful for explaining the implementation logic of a function or method, for instance. Or for generating API documentation. And file-level comments explaining the purpose of the class or module are always handy.

Anyone who writes Lisp without taking a moment to add a docstring to every definition would never get a job offer from me. (Not to mention comments as appropriate.)

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.

zonotope 8y ago

Clear and descriptive function names, concise and non-clever code, and a judicious use of well-named and concise helper functions are all way more valuable than docstrings. IMHO docstrings should be used as a last resort if the problem domain is truly complex enough to warrant it. Docstrings for trivial, well-named functions just get in the way, and if you feel the need to add a docstring to a complex function just after you've defined it, then I think that might be a hint that you should refactor the code to make it more clear and readable instead. An ns docstring that describes the intent of the api and docstrings for the major public interface functions are a good idea, but a blanket "docstring for every function" rule is a crutch to make up for unreadable, poorly-written code.

jogjayr 8y ago

If you have to write a comment to explain every definition, you've failed to make the code sufficiently readable and simple to understand IMHO. Code-level comments can become outdated without eagle-eyed code-reviewers. The code itself can never lie. Comments are a useful for explaining the implementation logic of a function or method, for instance. Or for generating API documentation. And file-level comments explaining the purpose of the class or module are always handy.