incubator-ooo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
Subject Re: Coding guideline or common rules
Date Fri, 20 Jul 2012 21:42:08 GMT
On 20 July 2012 22:22, Dennis E. Hamilton <dennis.hamilton@acm.org> wrote:
> I've seen the comment about SCMs being sufficient for tracing the provenance of code
and the changes that are made.  That puzzles me.
>
>  - History doesn't appear in source-code tarballs.
>  - It requires the original SCM repository or a history-preserving port of the SCN to
be available to interested parties.
>
> Basically, it is not a durable form of the information.

Indeed, especially since SVN log messages are not versioned.

I think log messages should only be used to inform the reader of the
commit message why the commit was done.
They should not be used for comments that are useful / necessary to
the reader of the code; those should be included as comments in the
code itself.
[Though of course such comments can go in the log message as well.]

However, does the end user of the source need to know provenance and history?

> Just sayin' ...

DItto.

>  - Dennis
>
> -----Original Message-----
> From: Pedro Giffuni [mailto:pfg@apache.org]
> Sent: Friday, July 20, 2012 12:52
> To: ooo-dev@incubator.apache.org
> Subject: Re: Coding guideline or common rules
>
> FWIW;
>
>
> ----- Original Message -----
> ...
>>
>> Hi,
>>
>> I just stumbled over a commit message for the new UOF filter.
>>
>> I think we should agree on a common guideline for our code and how we
>> contribute changes and bring them in the code.
>>
>> SCM's manage the change sets and the information who made the change,
>> that means we don't need further comments like this
>>
>> ///Begin Added by wangyumin for uof2-filter from cs2c
>> ...
>> /// End Added by wangyumin on 2012-2-22 14:32:18
>>
>> It is somewhat redundant and makes the code not really better readable.
>> Can we agree on the common understanding that we don't need such
>> comments and that we don't want them in the code. We should remove such
>> comments wherever we see or find them.
>>
>
> Indeed, I did mention in our local svn tutorial that those comments should be
> avoided. SVN does a wonderful job maintaining the origin information.
>
>> Any opinions?
>
>
> As a side note, I recently found similar prominent begin/end lines in another
> project and the culprit on that project was the GPLv2 section 2a:
>
> "You must cause the modified files to carry prominent notices stating
> that you changed the files and the date of any change."
>
>
> It's probable that old code from GPLd derivatives still carry such notes.
>
> Someone will have to clean them ;).
>
> Pedro.
>

Mime
View raw message