Why don't people understand this? I've spent a bit of time today on the AzPHP mailing list offering up reasons as to why inline API documentation is a bad thing (private list, so no link).
Think about it - a programming language is a way to declare what you want the computer to do. It's that simple. With a properly written program, all the API docs are doing is hiding the code that tells me exactly what is going on instead of what a programmer once knew - thought in a lot of cases - was going on. And if your code is so complex, or so convoluted that you have to document it in plain-English just to start to understand it, it's time to start refactoring.
This isn't to say I'm not a fan of documentation. I just differ from mainstream PHP in what form I look for. Give me a unit test any day over a three paragraph docblock. The test provides an assumption, the code to prove it, and an example of how I should actually use your code in - get this - real code. It's a win-win-win.
Ok - I'll hop off of my soap box now. Less than 60 hours to go until the pain and torture of this year's Dawn 'til Dusk. I'm waking up at night in a cold sweet sweat thinking about the two climbs this year.
12 comments
Cold sweet? Is that sorta like a cold sweat? :)
I generally just try to name my variables well and keep my code very organized so it's easy to see what's going on. I use in-line commenting to explain anything that looks squirrelly, like the fun array manipulations I seem to love doing.
Or those occasional "//yes, this really is going to dynamically reload when I include it" kind of comments for your bots? :-)
I completely agree. The more I write tests, more I want to see tests for other code, and the inline docs bother me. But the docs also prove very much useful now and then. I just wish there was a way of writing inline documentation without it being inline. :)
It doesn't matter if you write the clearest code in the world if your functions call other functions. Yes, I'm sure you can grok what something does by reading the source and chasing down all the functions and reading what they do, but a 3 paragraph doc block saves you from that effort. Not to mention that the documentation inline can help clarify the intent of the function, which is especially useful if you have a rarely executed code path with an inverted logic bug that didn't trigger until a couple of months after that code was written.
(Perhaps) more important than saving you effort is saving other developers effort. Those other developers may be people on your team, or they may be external parties that need to do something with it. Their programming skill may not be as good as yours and they may not know how to use the source, or they may misunderstand the source and do something wrong.
I work daily with a project that is > 275k lines of code (mostly C). At this scale the I-don't-need-inline-docs mentality becomes a serious liability.
I'm not commenting here to say "you're wrong", just to say, think ahead. You might not need those docs now, but what happens when your code base has grown--is someone going to have to retroactively document everything, or are you going to take a month out to explain how every function works to every new person that starts working on the code?
Yes, tests are good, and writing clear and concise code is also good. Inline docs achieve more good than evil :)
fett:
If you don't like them taking up screen estate then you should adopt an editor that can fold them out of your way.
(Perhaps) more important than saving you effort is saving other developers effort. Those other developers may be people on your team, or they may be external parties that need to do something with it. Their programming skill may not be as good as yours and they may not know how to use the source, or they may misunderstand the source and do something wrong.
I work daily with a project that is > 275k lines of code (mostly C). At this scale the I-don't-need-inline-docs mentality becomes a serious liability.
I'm not commenting here to say "you're wrong", just to say, think ahead. You might not need those docs now, but what happens when your code base has grown--is someone going to have to retroactively document everything, or are you going to take a month out to explain how every function works to every new person that starts working on the code?
Yes, tests are good, and writing clear and concise code is also good. Inline docs achieve more good than evil :)
fett:
If you don't like them taking up screen estate then you should adopt an editor that can fold them out of your way.
Good comments operate at a higher level of abstraction than tests. Imagine the comment: "This object acts like the $_SESSION array, except that it stores all session data under $_SESSION['appkey'], where 'appkey' is the value given to the constructor." That's way easier than any unit test, which by definition operates only one level removed from the source code itself.
Unless you like:
class AppSession implements ArrayAccess, IteratorAggregate, Countable {
protected $key;
function __construct($key) {
$this->key = (string) $key or throw new Exception("Must supply non-empty string(ification)");
function offsetGet($o) { return $_SESSION[$this->key][$o]; }
...
}
Unless you like:
class AppSession implements ArrayAccess, IteratorAggregate, Countable {
protected $key;
function __construct($key) {
$this->key = (string) $key or throw new Exception("Must supply non-empty string(ification)");
function offsetGet($o) { return $_SESSION[$this->key][$o]; }
...
}
Wez, I completely respect your opinion, but I disagree with what needs to be done to done to save effort of both yourself and future developers. At that point, what you're talking about is a manual that exists outside of the source code so it could be treated like a black-box. Perfect examples of this are the Zend Framework and PHP manuals. Those both provide excellent documentation, but the majority of helpful documentation isn't sitting right above the function signatures.
I wasn't clear enough in my initial post. It's not documentation per-say that I askew, it's the prevalent need of the PHP community to focus on API docs in the place of well written code and narrative docs.
I wasn't clear enough in my initial post. It's not documentation per-say that I askew, it's the prevalent need of the PHP community to focus on API docs in the place of well written code and narrative docs.
There's a distinct difference between docs for exported APIs that you want people to use, and internal APIs that are implementation details.
The former are typically what end up in manuals like the PHP and ZF docs, but the latter are not. Documentation being what it is, developers rarely have time to write it for the exported APIs, let alone the internal ones, so having a separate place to write those internal docs adds overhead to the development process, and is more prone to getting out of sync with the code.
I agree with your clarified sentiment, although I would broaden it to say that developers should try to keep an open mind about development methodology: don't close off something because there is no immediate need for it, and conversely, don't get too immersed in a technique that someone told you was good if it gets in the way of getting things done.
The former are typically what end up in manuals like the PHP and ZF docs, but the latter are not. Documentation being what it is, developers rarely have time to write it for the exported APIs, let alone the internal ones, so having a separate place to write those internal docs adds overhead to the development process, and is more prone to getting out of sync with the code.
I agree with your clarified sentiment, although I would broaden it to say that developers should try to keep an open mind about development methodology: don't close off something because there is no immediate need for it, and conversely, don't get too immersed in a technique that someone told you was good if it gets in the way of getting things done.
I think any reasonably large object oriented application will benefit greatly from documentation. Whether it is inline or not seems trivial. The real point is to tell others (including your future self) how the code works with other code not what the function returns, etc. Good documentation should say what a function is intended for and how it will be used by other areas in the application. Not having this information means that you must track down method calls which, again in a reasonably complex OO application, can lead to hours wasted.
Wez, I couldn't have closed out that comment better myself, even though I tend to be a bit of a methodology bigot (TDD) the majority of the time. I have to pull a quote from Jim Hugunin when asked about Python vs. Ruby vs. Whatever: "[TDD] just fits my brain better."
Alex, I do agree that it's trivial, but for me I want it out of the code. Reasonably complex OO does not me harder to understand necessarily. Properly named objects and carefully chosen method names tend to lead to code that is self-explanatory by it's simple usage. This gives me all of the information I need to know about it:
Alex, I do agree that it's trivial, but for me I want it out of the code. Reasonably complex OO does not me harder to understand necessarily. Properly named objects and carefully chosen method names tend to lead to code that is self-explanatory by it's simple usage. This gives me all of the information I need to know about it:
PersonDataMapper::findById($id) {
assert('is_int($id) || $id == (int)$id)');
}
My commenting style differs based on the thing I'm working on. When I'm doing a website with all the obvious simple stuff then I'm not going to be writing a line of comment for every line of code. On the other hand when I'm extending the functionality of e.g. the template engine in my framework I'm trying to write as much useful comments as I can. Just to make it easier when I'd have to be debugging or extending again :)
Comment feed for this post