Coding style

[ovainola]

To make the code style uniform, we could use the style recommended in the Julia documentation:
http://julia.readthedocs.org/en/latest/manual/style-guide/

The issue of the docstrings still seems to be undecided in the scene, but here's one suggestion:
http://stackoverflow.com/questions/19821247/how-to-make-user-defined-function-descriptions-docstrings-available-to-julia

issue open for more suggestions

[TeroFrondelius]

I think this is the same as #4. How do we join these two issues?

[ahojukka5]

We should also have some kind of measure how well our code is performing. Do functions have docstrings etc.? In Python there's such packages like pylint and pyflakes. We need something similar to this project also.

[TeroFrondelius]

Maybe you mean this: https://github.com/tonyhffong/Lint.jl

[TeroFrondelius]

Maybe also this is relevant: https://github.com/astrieanna/TypeCheck.jl

[TeroFrondelius]

https://groups.google.com/forum/#!searchin/julia-users/lint/julia-users/FIT1HS-_ZQk/MK1SbbwOvToJ

In my package tests I normally run Lint.jl as the last thing with...

# run lint
println("Running Lint...")
lintpkg("MyPkg")

Maybe it would help if we put Lint into the default REQUIRE in package generation and the above lines >into test/runtests.jl?

[TeroFrondelius]

Important decision. How many spaces we should use. We noticed with @ahojukka5 that we have different default settings. I was using Juno, thus I believe, without knowing, it should be the style of Julia.

[ahojukka5]

Let's use what's default in Juno. In notebooks it's 4 spaces what is
causing differences. While Julia doesn't care about indent spaces we should
use just one style.

On Tue, Jun 23, 2015 at 11:05 PM, Tero Frondelius notifications@github.com
wrote:

Important decision. How many spaces we should use. We noticed with
@ahojukka5 https://github.com/ahojukka5 that we have different default
settings. I was using Juno, thus I believe, without knowing, it should be
the style of Julia.

—
Reply to this email directly or view it on GitHub
#5 (comment).

terveisin,
Jukka Aho

[TeroFrondelius]

I need to correct myself. Juno seems to have two spaces as a default.

[TeroFrondelius]

Is this now solved? Should we make a test to check the code indentation?

[ahojukka5]

Well... We need to figure out how to change indent to 2 characters in IJulia or 4 characters in Juno.

[tkelman]

Contributions to base Julia recommend 4-space indent. The fact that Juno's default doesn't match that is a bug that has not been fixed yet in Juno, but should be - JuliaIDE/Julia-LT#167

[ahojukka5]

I updated CONTRIBUTING.md for that.

[ahojukka5]

I added automatic Lint check, see http://juliafem.kapsi.fi/quality/index.html

I think this issue is now done.

[TeroFrondelius]

Cool.

[ahojukka5]

I reopened this issues because we haven't decided yet our docstring style. We definitely need to update contributing.md for this important decision. Here's some options

1. numpy docstyle. Already well documented process, style guide is well done and mature.
2. julia docstyle. I haven't found this document yet.
3. something totally different, and we have to write our own style guide and no other project uses it.

[ahojukka5]

I don't like the idea of using Markdown at all. First of all it lacks standards. If you look at http://goo.gl/aDlLdB there's Markdown, Markdown/strict, PHP Markdown Extra, Github Markdown and Multimarkdown. Seems like everyone has stabbed the original markdown to get some nice extra features which are not originally described. Sounds confusing. Another thing is that #-character is used to comment in Julia so basically some "incorrect" commenting could basically break the documentation system.

[ovainola]

I only found styles for

• how to write functions, http://docs.julialang.org/en/latest/manual/style-guide/
• how to create documentation, http://julia.readthedocs.org/en/latest/manual/documentation/

but no style for how to write documentation

[ahojukka5]

I guess it doesn't exist or is very well hidden. So what alternatives do we have? Use numpy style or don't document code at all? We need to have some styling guide or reference to one or otherwise every function is written using different documentation style.

[ovainola]

+1 for numpy style, since it's quite popular with scientific libraries (numpy, scipy, ...) and
"""- Numpydoc

Note that Numpy recommend to follow their own numpydoc based on Google format and usable by Sphinx.""" - http://stackoverflow.com/questions/3898572/what-is-the-standard-python-docstring-format. Even though it's python style is quite good format for writing docstring

[ovainola]

update:
"Documentation is very free-form; there are no set formatting restrictions or strict conventions. It’s hoped that best practices will emerge fairly naturally as package developers learn to use the new system." http://julia.readthedocs.org/en/latest/manual/documentation/

[TeroFrondelius]

Numpy style ok for me. Will we get the doctests to work with Numpy style?

[ahojukka5]

In principle yes, because doctests, document generation system (sphinx / mkdocs) and markup language (rst / md) are all different things. But we need to write some parser to use numpy style in Lexicon because it uses Markdown.jl by default. Numpy commity has already done their modifications to get style working with sphinx, maybe we could get something from there...

[ahojukka5]

http://juliafem.kapsi.fi/api/JuliaFEM.elasticity_solver.html this is current situation.

[ahojukka5]

I updated contributing.md for numpydoc. Now we can close this topic.