(31) “Avoid overcommenting” seems like a better phrase. What I’d like to get across is that often comments are really formal specifications and belong in a separate document. I use to fill the DataFrames codebase with architectural design information as comments, which started to become clutter that made the file hard to read over time.
(10) I think using more spaces is consistently more readable. I’ve never understood why keyword arguments should have a special set of rules applied to them that makes them hard to read. Consistency with other constructs is also a big gain. Noting something about BigFloats seems worth doing to me. — John On Dec 31, 2013, at 10:24 AM, Alessandro Jake Andrioni <[email protected]> wrote: > Sounds nice! > > After a first skim, my comments are: > > (31): I'm not sure if minimizing comments is a good idea. Maybe > something like "Avoid commenting trivial stuff" or "Avoid > overcommenting" is a better alternative, since the problem isn't > really with comments in general, but with extraneous/unneeded > comments. > > (10): Any special reasons for this other than consistency? > > Maybe something about BigFloats (creating from a string instead of > creating from a literal) could be nice, but I'm not sure if it's > general enough to be included. > > On 31 December 2013 13:01, John Myles White <[email protected]> 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 >>
