Re: [Ksummit-discuss] [CORE-TOPIC] Documentation

[David Woodhouse <dwmw2@infradead.org>]

[-- Attachment #1: Type: text/plain, Size: 1086 bytes --]

On Mon, 2015-07-13 at 12:37 -0400, Steven Rostedt wrote:
> There's been times where I look at other subsystems and wonder WTF a
> function is suppose to do. Perhaps I need to start poking the author 
> of that code to explain it.

That should never happen. It's OK if you just don't know how to do
something (or don't even know if it's possible), and you have to ask or
resort to documentation.

But you, Steven, should *never* find yourself looking at a function and
wondering WTF it does. If a function is complex enough that you need an
explanation, then either:

 1. It should have been made simpler, or 
 2. There should be an explanation *right* there in the C file.

Those should be caught in review. Too often, I think, we allow opaque
code to get merged.

I'm guilty of it myself. And I've also suffered from it. Sometimes,
with a few years in between, I have even inflicted this pain on
*myself* :)

-- 
David Woodhouse                            Open Source Technology Centre
David.Woodhouse@intel.com                              Intel Corporation

[-- Attachment #2: smime.p7s --]
[-- Type: application/x-pkcs7-signature, Size: 5691 bytes --]