[cobbler-devel] Code/documentation conventions

Jörgen Maas jorgen.maas at gmail.com
Wed Apr 9 13:23:41 UTC 2014


Hi Alan,

Well, again. I could't agree more with you. I have marked this conversation
as something that should be done during the Cobbler 2.7 development cycle.
I will follow up on this after the 2.6 release, which i finally got around
to right now.

Feel free to send any patches targeting master!

Once again, thanks!


On Mon, Mar 24, 2014 at 4:37 PM, Alan Evangelista <alanoe at linux.vnet.ibm.com
> wrote:

> I noticed Cobbler does not apply some conventions used in other Python
> projects. I have some suggestions:
>
> * Validate code using Pylint
>  * Comment: I think this is fundamental to find subtle errors (eg
> referencing inexistent variables). I have already fixed all Pylint errors I
> could in my Cobbler clone and I just ignored those few I cannot fix (eg in
> templating classes). I could submit relevant patches upstream. I'll soon
> automate Pylint checks in any patch submitted by my team, possibly Cobbler
> upstream could do the same.
>
> * Introduce documentation convention
>  * Motivation: makes documentation easier to read and write
>  * Suggestions:
>   * Sphinx restructuredText extensions (http://sphinx-doc.org/
> domains.html#signatures) .
>   * simple Javadoc-style documentation convention. eg document methods are
> documented with method description, @param <type> <var_name>
> <var_description> for each parameter and @return <type>
> <return_var_description> for return value. My team uses that and it works
> well.
>  * Comment: I consider param/return type specially useful, as Python does
> not declare variable types in method definition.
>
> * Validate code using PEP8 (Python style guide)
>
> * Order imports alphabetically. Possibly, split imports in standard Python
> imports, third-party imports and Cobbler imports.
>  * Motivation: readability
>
> * Remove trailing whitespaces
>  * Motivation: remove commit noise. I see other reasons at
> http://programmers.stackexchange.com/questions/121555/why-is-trailing-
> whitespace-a-big-deal , but imho they are minor.
>
>
> Maybe some of these suggestions have already been considered in the past
> and rejected. If you could share with me these reasons, it'd be much
> appreciated.
>
>
> Regards,
> Alan Evangelista
>
> _______________________________________________
> cobbler-devel mailing list
> cobbler-devel at lists.fedorahosted.org
> https://lists.fedorahosted.org/mailman/listinfo/cobbler-devel
>



-- 
Grtz,
Jörgen Maas
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.fedorahosted.org/pipermail/cobbler-devel/attachments/20140409/e6dc350a/attachment.html>


More information about the cobbler-devel mailing list