On Wed, Jan 1, 2014 at 12:35 AM, John Myles White
johnmyleswh...@gmail.comwrote:
(4) Using both tabs and spaces is a huge problem in a shared codebase.
This is probably the only rule in my entire list that I’m actually going to
enforce in the code I maintain. IIRC, Python completely forbids mixing
these kinds of space characters at the language level.
+1
IMHO tabs should totally be avoided. We can configure our editors/IDE to
behave tabs like spaces.
I know vim does that [set expandtab], and we can use tab key for all
general purpose and it expands
to spaces.
(7) + (8) These rules are part of the official Google style guides for R,
which is the language with the most similarity to Julia that’s being used
at companies with public facing style guidelines. I think they’re quite
sensible rules, which is why I decided to borrow them from published
standards.
(18) + (19): This is clearly an area of big disagreement in our community.
I might pull them out into a suggestions section since I’d really prefer
that code submitted to things like DataFrames.jl follow this rule, but
don’t want to include a rule that’s going to be a big schism in the
community.
(22) + (23) + (24): I may take these out as well. I definitely agree that
there’s a big difference between performance guidelines and style
guidelines, although that line is blurry when you’re trying to keep a
codebase written in a consistent style.
(31): Comments aren’t PDF’s or HTML or any other language designed for
transmitting carefully formatted documents. You don’t get to use images,
properly formatted tables, etc. I find diagrams are an essential part of
good documentation. I think conflating documents with code leads to
documents that are less readable and lots of lines in code that’s not
actually worth reading.
(35): I might take this one out as well. It’s somewhere on the boundary
between a performance tip and a style habit worth developing.
— John
On Dec 31, 2013, at 11:12 AM, Daniel Carrera dcarr...@gmail.com wrote:
Personally, I do not think that a more thorough style guide is
necessarily better. That said, I will give you my comments:
(4): I like tabs and I use them.
(7) + (8): I disagree. Although I generally use comma+space as you say,
at times I deviate from that when I feel that doing so will improve the
clarity and readability of my code.
(18)+(19): I disagree. Although I could favour rules like this in a
particular project, in many cases I think that adding type annotations just
creates syntactic noise and can create a needless limitation.
(22)+(23)+(24): I do not think that performance tips belong in a style
guide. You could spend a lot of time writing performance tips and I don't
see an obvious reason why the three tips you chose are more important than
other performance tips.
(31): I partially disagree. I like writing documentation (e.g. tutorial
or explaining an algorithm) at the top of the file. I like having the
documentation in the same file as the code that it refers to. I do not know
what you mean when you say that English documents are more readable when
not constrained by the rule of code comments. What rules are those?
Also, I rarely want to have a diagram in my documentation because that
involves starting a WYSIWYG program like LibreOffice or something like
that. I haven't really felt a lot of need for diagrams.
(35): This doesn't sound like a style thing either. Advice on the
correct way to use a module, or how to maintain precision or avoid
round-off errors, do not belong in a style guide. This sort of thing
belongs in either the documentation for the module, or on some tutorial
about numerical computation.
Cheers,
Daniel.
On Tuesday, 31 December 2013 10:01:23 UTC-5, John Myles White wrote:
One of the things that I really like about working with the Facebook
codebase is that all of the code was written to comply with a very thorough
internal style guideline. This prevents a lot of useless disagreement about
code stylistics and discourages the creation of unreadable code before
anything reaches the review stage.
In an attempt to emulate that level of thoroughness, I decided to extend
the main Julia manual’s style guide by writing my own personal style
guideline, which can be found at
https://github.com/johnmyleswhite/Style.jl
I’d be really interested to know what others think of these rules and
what they think is missing. Right now, my guidelines leave a lot of wiggle
room.
— John
