Talk:Style Guidelines
Responses so far: Günther:
- local headers before system headers
- don't forbid public data members
- <!Guenther> Demanding Doygen comments is also a very radical change
- <!Guenther> Doxygen is only really usefull if you are generating API docs that are intended to be read without looking at the source code
- <!Guenther> That's not a use case for us: our API is C4Script, not some C++ API
PeterW:
- order switch members by numeric value
Afterthoughts Isilkor:
- Use forward declarations instead of including the header inside other headers, if possible.
Opinions:
- Use anonymous namespaces instead of static: In favor: ck, Isilkor; Against: Günther, PeterW
- Doxygen comments: In favor:; Against: Günther, PeterW
The document should describe reality, not wishful thinking. Where reality is inconsistent, the document can describe which of several options is preferred, but it shouldn't contain anything that's not already in somewhat widespread use. That would mean changing the coding style, and that's not the job of a coding style document. --Günther 16:41, 4 August 2009 (UTC)
- The document is intended to describe guidelines for new code, and not the legacy code that's all over the place anyway. While it's probably preferable to change old code if you do work in the vicinity, I certainly don't expect the code to be changed/reformatted on its own. --Isilkor 17:35, 4 August 2009 (UTC)
- I think the intention of a Coding Style document should be to ensure uniformity. For that, you have to describe what's already in use. And the Clonk source code really is not that much "all over the place". For example, the majority of files use indented braces, thus the coding style has to prescribe that, however much we would want to have another brace style. --Günther 11:36, 5 August 2009 (UTC)
- No, it really is all over the place. Just take a look at standard. It's not even uniform within single files. There's mixed brace styles, tabs and spaces are both used for indenting (sometimes interspersed in the same function), you have a healthy mix of formatting in "section heading" comments, and so on. --Isilkor 14:01, 5 August 2009 (UTC)
- I'd argue that those are exceptions. Almost all new code uses tabs, only old code differs and when somebody configured their editor for two-space-tabs and I didn't notice the issue. (If you do configure your editor for two-space-tabs, the all-over-the-placeness vanishes from sight ;-), so I do not recommend that.) The brace style is a bigger issue because nobody tried to enforce uniformity there, but on the other hand I think the old code is more consistent in that regard, and overall there's a clear majority. Section heading comments are inconsistent, true, but they are also rare.--Günther 15:57, 5 August 2009 (UTC)
- No, it really is all over the place. Just take a look at standard. It's not even uniform within single files. There's mixed brace styles, tabs and spaces are both used for indenting (sometimes interspersed in the same function), you have a healthy mix of formatting in "section heading" comments, and so on. --Isilkor 14:01, 5 August 2009 (UTC)
- I think the intention of a Coding Style document should be to ensure uniformity. For that, you have to describe what's already in use. And the Clonk source code really is not that much "all over the place". For example, the majority of files use indented braces, thus the coding style has to prescribe that, however much we would want to have another brace style. --Günther 11:36, 5 August 2009 (UTC)
I would not restrict the order of case labels in a switch. But if we do, then I agree with PeterW that they should be ordered by numeric value (which, for enumeration values, is mostly the same as the order the enumerators are defined). Maybe we also want to note that for commenting out code, #if 0 is preferred. I am generally okay with these guidelines, though I'm likely to have problems with a few I'm not used to, especially the pointer asterisk position and the space following if/while/for. When I am writing code then I am paying attention to the code and not the style, and I often fall back to my own style without even noticing. So please don't punch me if I check in code that doesn't strictly obey the guidelines. --Clonk-Karl 00:23, 5 August 2009 (UTC)