10up/Engineering-Best-Practices — pull request #50 by jamesmehorter (2014-11-19 14:52:40+00:00)
Title: Docblock Long Description Emphasis

Hey all.. trying to put some more emphasis on the use of verbose doblock long descriptions to communicate code purpose, intent, and context. Ideally, each function/heavy logic section of code (any language!) should include a long description primarily for future maintainability. Most assuredly, another engineer will someday need to work on your code, when you're long gone. Knowing WHY the code was written, and what it's purpose is within the larger project/context is invaluable when another engineer is onboarded to make edits later on.

The secondary purpose for these is so managers/clients can easily understand what's going on without reading the code. Think of these as code manuals, just as Ford ships one with each automobile; we should be doing the same for each piece of code we write.

The current WordPress Documentation Standards just state that a long description should be included, but I think we can do A LOT better than that! We can emphasize documenting code on a thoughtful level, imagining the questions the next engineer would ask and answering them ahead of time.

Please let me/us know what you think! Feedback is greatly encouraged!!! :)