(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.
(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 <[email protected]> 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 >
