Code documentation
|
View:
New views
5 Messages
—
Rating Filter:
Alert me
|
 |
Code documentation
by Oliver Charles-2
::
Rate this Message:
Hi,
I wanted to discuss with the developers their stance on inline code documentation. I personally am very much against it - it impairs the readability of the source code itself (decreasing the signal to noise, if you will) and rapidly falls out of sync with the code itself. Furthermore, I've never actually looked at any of the documentation itself, nor generated it in HTML to read along side while I'm working. I see code documentation as an essential practice for APIs that are going to be used be vast amounts of people, but for inhouse code (ie, MusicBrainz) I see very little need for it. What do other people think? -- Oliver Charles / aCiD2 _______________________________________________ MusicBrainz-devel mailing list MusicBrainz-devel@... http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel |
|
|
Re: Code documentation
by Bugzilla from lalinsky@gmail.com
::
Rate this Message:
On Thu, Sep 10, 2009 at 4:17 PM, Oliver Charles
<oliver.g.charles@...> wrote: > Hi, > > I wanted to discuss with the developers their stance on inline code > documentation. I personally am very much against it - it impairs the > readability of the source code itself (decreasing the signal to noise, > if you will) and rapidly falls out of sync with the code itself. > Furthermore, I've never actually looked at any of the documentation > itself, nor generated it in HTML to read along side while I'm working. > > I see code documentation as an essential practice for APIs that are > going to be used be vast amounts of people, but for inhouse code (ie, > MusicBrainz) I see very little need for it. > > What do other people think? I'm surprised you are against it, because you have been writing a lot of POD documentation, especially in the TT branch. I completely agree that we don't need it in most cases, because the code is self-documenting and in cases we need it, it should be written separately. -- Lukas Lalinsky lalinsky@... _______________________________________________ MusicBrainz-devel mailing list MusicBrainz-devel@... http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel |
|
|
Re: Code documentation
by Oliver Charles-2
::
Rate this Message:
2009/9/10 Lukáš Lalinský <lalinsky@...>:
> On Thu, Sep 10, 2009 at 4:17 PM, Oliver Charles > <oliver.g.charles@...> wrote: >> Hi, >> >> I wanted to discuss with the developers their stance on inline code >> documentation. I personally am very much against it - it impairs the >> readability of the source code itself (decreasing the signal to noise, >> if you will) and rapidly falls out of sync with the code itself. >> Furthermore, I've never actually looked at any of the documentation >> itself, nor generated it in HTML to read along side while I'm working. >> >> I see code documentation as an essential practice for APIs that are >> going to be used be vast amounts of people, but for inhouse code (ie, >> MusicBrainz) I see very little need for it. >> >> What do other people think? > > I'm surprised you are against it, because you have been writing a lot > of POD documentation, especially in the TT branch. I completely agree > that we don't need it in most cases, because the code is > self-documenting and in cases we need it, it should be written > separately. Well, I thought this might come up :) I did start off writing POD documentation, because it "feels" right, but I've learn that there really doesn't seem to be a need. Also, POD is a bit different because it's after all the source code, so it doesn't impair readability so much. But I don't think I've written any more for a few months now, which is proof that documentation will bit-rot unless we put the extra effort in to maintain that too. -- Oliver Charles / aCiD2 _______________________________________________ MusicBrainz-devel mailing list MusicBrainz-devel@... http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel |
|
|
Re: Code documentation
by Paul Taylor-9
::
Rate this Message:
Oliver Charles wrote:
> 2009/9/10 Lukáš Lalinský <lalinsky@...>: > >> On Thu, Sep 10, 2009 at 4:17 PM, Oliver Charles >> <oliver.g.charles@...> wrote: >> >>> Hi, >>> >>> I wanted to discuss with the developers their stance on inline code >>> documentation. I personally am very much against it - it impairs the >>> readability of the source code itself (decreasing the signal to noise, >>> if you will) and rapidly falls out of sync with the code itself. >>> Furthermore, I've never actually looked at any of the documentation >>> itself, nor generated it in HTML to read along side while I'm working. >>> >>> I see code documentation as an essential practice for APIs that are >>> going to be used be vast amounts of people, but for inhouse code (ie, >>> MusicBrainz) I see very little need for it. >>> >>> What do other people think? >>> >> I'm surprised you are against it, because you have been writing a lot >> of POD documentation, especially in the TT branch. I completely agree >> that we don't need it in most cases, because the code is >> self-documenting and in cases we need it, it should be written >> separately. >> > > Well, I thought this might come up :) I did start off writing POD > documentation, because it "feels" right, but I've learn that there > really doesn't seem to be a need. Also, POD is a bit different because > it's after all the source code, so it doesn't impair readability so > much. But I don't think I've written any more for a few months now, > which is proof that documentation will bit-rot unless we put the extra > effort in to maintain that too. > > documentation shouldn't swamp the code. But if you do write it - it should be within the code, and updated as the code changes. This is the only way its not going to get out of date, document separately and its impossible to maintain, unless youre talking about overview/design docs. Paul _______________________________________________ MusicBrainz-devel mailing list MusicBrainz-devel@... http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel |
|
|
Re: Code documentation
by Robert Kaye
::
Rate this Message:
+1
In reviewing code, I've not felt that I was missing comments. When comments were warranted (say in ngs conversion scripts) they were present. On Sep 10, 2009, at 7:45 AM, Lukáš Lalinský wrote: > I completely agree > that we don't need it in most cases, because the code is > self-documenting and in cases we need it, it should be written > separately. -- --ruaok "Vague, but exciting..." -- Mike Sendall on the WWW proposal. Robert Kaye -- rob@... -- http://mayhem-chaos.net _______________________________________________ MusicBrainz-devel mailing list MusicBrainz-devel@... http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel |
| Free embeddable forum powered by Nabble | Forum Help |
