Coding Guidelines on Wiki

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

Coding Guidelines on Wiki

Raul Kripalani
I have clarified examples in the Wiki and I've added lots of TODOs for
rules that must be defined to avoid subjective bias.

Please review my changes and let's define an action plan:

https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=57901455&selectedPageVersions=15&selectedPageVersions=14

I'd rather overspecify than underspecify.

Regards,

*Raúl Kripalani*
PMC & Committer @ Apache Ignite, Apache Camel | Integration, Big Data and
Messaging Engineer
http://about.me/raulkripalani | http://www.linkedin.com/in/raulkripalani
http://blog.raulkr.net | twitter: @raulvk
Reply | Threaded
Open this post in threaded view
|

Re: Coding Guidelines on Wiki

dsetrakyan
On Tue, Sep 29, 2015 at 2:05 PM, Raul Kripalani <[hidden email]> wrote:

> I have clarified examples in the Wiki and I've added lots of TODOs for
> rules that must be defined to avoid subjective bias.
>
> Please review my changes and let's define an action plan:
>
>
> https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=57901455&selectedPageVersions=15&selectedPageVersions=14
>
> I'd rather overspecify than underspecify.
>

Raul, do we really need to require the @author tag? I think it should be
optional.


>
> Regards,
>
> *Raúl Kripalani*
> PMC & Committer @ Apache Ignite, Apache Camel | Integration, Big Data and
> Messaging Engineer
> http://about.me/raulkripalani | http://www.linkedin.com/in/raulkripalani
> http://blog.raulkr.net | twitter: @raulvk
>
Reply | Threaded
Open this post in threaded view
|

Re: Coding Guidelines on Wiki

Raul Kripalani
On Tue, Sep 29, 2015 at 1:22 PM, Dmitriy Setrakyan <[hidden email]>
wrote:

> Raul, do we really need to require the @author tag? I think it should be
> optional.
>

That's what the coding style said:

    "Every type should start with at least minimal Javadoc comments
including description and author information in the following form:"

All I did was fix the example in accordance with the rule. Now you see
where I'm coming from – huh? ;-)

NOTE: I personally dislike this coding style, so this task of helping the
community improve the definitions of something I dislike is arduous for me.

I'm more akin to Google's Java style:
https://google.github.io/styleguide/javaguide.html. It's more commonplace,
neutral and less rigid.

Regards,

*Raúl Kripalani*
PMC & Committer @ Apache Ignite, Apache Camel | Integration, Big Data and
Messaging Engineer
http://about.me/raulkripalani | http://www.linkedin.com/in/raulkripalani
http://blog.raulkr.net | twitter: @raulvk
Reply | Threaded
Open this post in threaded view
|

Re: Coding Guidelines on Wiki

Konstantin Boudnik-2
In reply to this post by dsetrakyan
On Tue, Sep 29, 2015 at 02:22PM, Dmitriy Setrakyan wrote:

> On Tue, Sep 29, 2015 at 2:05 PM, Raul Kripalani <[hidden email]> wrote:
>
> > I have clarified examples in the Wiki and I've added lots of TODOs for
> > rules that must be defined to avoid subjective bias.
> >
> > Please review my changes and let's define an action plan:
> >
> >
> > https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=57901455&selectedPageVersions=15&selectedPageVersions=14
> >
> > I'd rather overspecify than underspecify.
> >
>
> Raul, do we really need to require the @author tag? I think it should be
> optional.

I can not find the proof-link right now, but I believe @author isn't option -
it shouldn't be used at all. There reason is purely legal: the code belongs to
the Apache, so stating ownership otherwise simply should not happen.

Cos

Reply | Threaded
Open this post in threaded view
|

Re: Coding Guidelines on Wiki

Raul Kripalani
I never use @author tags in other projects – but it was a requirement in
Ignite's Coding Style, that's why I added it to the example.

I'm -1 for @author tags, in fact. They not useful for code maintenance (as
the body of the @authored block can change line by line – better use git
blame or git log to find out who the author was) nor for meritocracy
purposes, as no one will dig in so deep and we already have a Team page to
list participants.
Reply | Threaded
Open this post in threaded view
|

Re: Coding Guidelines on Wiki

Konstantin Boudnik-2
On Tue, Sep 29, 2015 at 02:09PM, Raul Kripalani wrote:
> I never use @author tags in other projects – but it was a requirement in
> Ignite's Coding Style, that's why I added it to the example.

Good spotting and it needs to be removed of course. Thanks for bringing this
up!

> I'm -1 for @author tags, in fact. They not useful for code maintenance (as
> the body of the @authored block can change line by line – better use git
> blame or git log to find out who the author was) nor for meritocracy
> purposes, as no one will dig in so deep and we already have a Team page to
> list participants.

yup.

Cos

Reply | Threaded
Open this post in threaded view
|

Re: Coding Guidelines on Wiki

Dmitriy Setrakyan
In reply to this post by Raul Kripalani
I think no one will object to removing the @author tag from the guidelines. I think it is there right now by mistake.

Dmitriy



> On Sep 29, 2015, at 3:09 PM, Raul Kripalani <[hidden email]> wrote:
>
> I never use @author tags in other projects – but it was a requirement in
> Ignite's Coding Style, that's why I added it to the example.
>
> I'm -1 for @author tags, in fact. They not useful for code maintenance (as
> the body of the @authored block can change line by line – better use git
> blame or git log to find out who the author was) nor for meritocracy
> purposes, as no one will dig in so deep and we already have a Team page to
> list participants.
Reply | Threaded
Open this post in threaded view
|

Re: Coding Guidelines on Wiki

nivanov
In reply to this post by Raul Kripalani
+1 on -1 for @author tag. It's a remnant of the long distant past...

--
Nikita Ivanov


On Tue, Sep 29, 2015 at 6:09 AM, Raul Kripalani <[hidden email]> wrote:

> I never use @author tags in other projects – but it was a requirement in
> Ignite's Coding Style, that's why I added it to the example.
>
> I'm -1 for @author tags, in fact. They not useful for code maintenance (as
> the body of the @authored block can change line by line – better use git
> blame or git log to find out who the author was) nor for meritocracy
> purposes, as no one will dig in so deep and we already have a Team page to
> list participants.
>