Separate positioning and visuals
owenversteeg opened this issue · 7 comments
Currently, when someone reads through the codebase it's occasionally difficult to distinguish between a property intended for positioning and a property intended for visual effect.
For example:
- the first few lines of grid.less
- most places where padding is involved, the situation is ambiguous (especially for newcomers)
- a large portion of navbar.less
This could be fixed by marking positioning properties with ALL CAPS, a Capitalfirstletter, CamelCase or camelCase (as CSS is case-insensitive in property names)
that works only if someone knows why certain properties are handled differently than others though. it also then becomes an unconventional coding practice that we would have to enforce on ourselves and other potential contributors.
It may make more sense to just extend documentation to explain what the code is doing. I'm not sure about less, but in sass at least, there are sass-specific comments using // and those comments don't get exported when compiling the CSS. (or just regular comments could be used since they get killed in minification & gzipping anyway)
if we don't want to put the comments into the files (as duplication/potential out dating between the two versions of the code base comes into play here), a single separate readme file could be created to document what's going on in each section of the code base. (i think i like this one best).
Hmm, I see your point about an unconventional coding practice. These look like the options:
- Strange case
- Pros: doesn't affect the CSS output, works with both LESS and Sass, is easy to use, doesn't make the (uncompiled) files larger, least verbose
- Cons: unconventional coding style
- Comments
- Pros: conventional, easy to use
- Cons: more keystrokes, a bit more verbose
- Separate README
- Pros: prevents duplication/outdating of comments
- Cons: more work to maintain, more verbose, people need to switch between two files
I'm more of a fan of comments and/or a different case; a README seems a bit too much work and people reading it would have to switch between two files. Of course, with case the issue becomes whether or not people would be put off by a different coding convention. That said, plenty of programs have unconventional coding conventions and still do well.
yeah, i'm still leaning towards either comments or the readme.
the con to comments isn't really that big of a con, as documentation either way is going to result in more keystrokes. if anything, the con for comments would be that they would be harder to maintain as they would need to be updated across the two code bases.
the readme, while yes being in a separate file, would at least be all documentation in one place. if anything, depending on how in depth the documentation needs to be, the readme could end up being less work because the padding/sizing rules could be explained in a global sense...where as if the comments are separated in different files, certain explanations (or similar explanations) might need to be repeated.
e.g. file 1: "padding is used in this x rule set to do Y"
file 2: "padding is used in this x rule set to do Y +1"
With that all being said, a counter point to my argument for the readme is that there are certain bits of documentation that already exist in the Sass files, and it may be stranger yet to have some documentation within the files, and some in another file.
So, I'm circling back here and saying that either the readme or comments would work just fine by me.
Ok, sounds good. I personally prefer comments to a readme, and they're fairly easy to add. I think they should be inline, and only used when necessary.
I suppose the next step is to actually add the comments. Do you have any particular suggestions of where to add them?
If they're comments that describe the file on a global scale, they should go at the top. If they're describing a particular bit of CSS that's specific to a single line, it should go as close to that line as possible.
That's how I do it on my files / have seen others do it as well
Sent from my iPhone
On Jan 29, 2014, at 11:09 PM, Owen Versteeg notifications@github.com wrote:
Ok, sounds good. I personally prefer comments to a readme, and they're fairly easy to add. I think they should be inline, and only used when necessary.
I suppose the next step is to actually add the comments. Do you have any particular suggestions of where to add them?
—
Reply to this email directly or view it on GitHub.
Sounds good. I'll start adding more comments later.
With my recent commits this issue seems to be mostly resolved - in most places where files need comments they have them. I don't think strange casing is necessary.