Talk:Style Guidelines - Revision history

Isilkor: moved User talk:Isilkor/Style Guidelines to Talk:Style Guidelines: These are now policy

2009-10-24T16:56:30Z

moved User talk:Isilkor/Style Guidelines to Talk:Style Guidelines: These are now policy

← Older revision		Revision as of 16:56, 24 October 2009
Line 21:		Line 21:
	:: 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. --[[User:Günther\|Günther]] 11:36, 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. --[[User:Günther\|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. --[[User:Isilkor\|Isilkor]] 14:01, 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. --[[User:Isilkor\|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.--[[User:Günther\|Günther]] 15:57, 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. --[[User:Clonk-Karl\|Clonk-Karl]] 00:23, 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. --[[User:Clonk-Karl\|Clonk-Karl]] 00:23, 5 August 2009 (UTC)

Isilkor at 14:01, 5 August 2009

2009-08-05T14:01:20Z

← Older revision		Revision as of 14:01, 5 August 2009
Line 19:		Line 19:
	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. --[[User:Günther\|Günther]] 16:41, 4 August 2009 (UTC)		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. --[[User:Günther\|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. --[[User:Isilkor\|Isilkor]] 17:35, 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. --[[User:Isilkor\|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. --[[User:Günther\|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. --[[User:Isilkor\|Isilkor]] 14:01, 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. --[[User:Clonk-Karl\|Clonk-Karl]] 00:23, 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. --[[User:Clonk-Karl\|Clonk-Karl]] 00:23, 5 August 2009 (UTC)

Clonk-Karl: Commented guidelines

2009-08-05T00:23:29Z

Commented guidelines

← Older revision		Revision as of 00:23, 5 August 2009
Line 14:		Line 14:

	Opinions:		Opinions:
	* Use anonymous namespaces instead of static: '''In favor:''' ck?, Isilkor; '''Against:''' Günther, PeterW		* Use anonymous namespaces instead of static: '''In favor:''' ck, Isilkor; '''Against:''' Günther, PeterW
	* Doxygen comments: '''In favor:'''; '''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. --[[User:Günther\|Günther]] 16:41, 4 August 2009 (UTC)		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. --[[User:Günther\|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. --[[User:Isilkor\|Isilkor]] 17:35, 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. --[[User:Isilkor\|Isilkor]] 17:35, 4 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. --[[User:Clonk-Karl\|Clonk-Karl]] 00:23, 5 August 2009 (UTC)

Isilkor: Intended for new code

2009-08-04T17:35:42Z

Intended for new code

← Older revision		Revision as of 17:35, 4 August 2009
Line 16:		Line 16:
	* Use anonymous namespaces instead of static: '''In favor:''' ck?, Isilkor; '''Against:''' Günther, PeterW		* Use anonymous namespaces instead of static: '''In favor:''' ck?, Isilkor; '''Against:''' Günther, PeterW
	* Doxygen comments: '''In favor:'''; '''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. --[[User:Günther\|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. --[[User:Isilkor\|Isilkor]] 17:35, 4 August 2009 (UTC)

Isilkor at 15:34, 4 August 2009

2009-08-04T15:34:01Z

← Older revision		Revision as of 15:34, 4 August 2009
Line 2:		Line 2:
	[[User:Günther\|Günther]]:		[[User:Günther\|Günther]]:
	* local headers before system headers		* local headers before system headers
	* use static instead of anonymous namespaces
	* don't forbid public data members		* don't forbid public data members
	* <!Guenther> Demanding Doygen comments is also a very radical change		* <!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> 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		: <!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 [[User:Isilkor\|Isilkor]]:		Afterthoughts [[User:Isilkor\|Isilkor]]:
	* Use forward declarations instead of including the header inside other headers, if possible.		* 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

Isilkor: fwd decls

2009-08-04T15:00:53Z

fwd decls

← Older revision		Revision as of 15:00, 4 August 2009
Line 7:		Line 7:
	: <!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> 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		: <!Guenther> That's not a use case for us: our API is C4Script, not some C++ API
			Afterthoughts [[User:Isilkor\|Isilkor]]:
			* Use forward declarations instead of including the header inside other headers, if possible.

Isilkor: Responses: Günther

2009-08-04T00:17:28Z

Responses: Günther

New page

Responses so far:
[[User:Günther|Günther]]:
* local headers before system headers
* use static instead of anonymous namespaces
* 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

← Older revision		Revision as of 16:56, 24 October 2009
Line 21:		Line 21:
	:: 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. --[[User:Günther\|Günther]] 11:36, 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. --[[User:Günther\|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. --[[User:Isilkor\|Isilkor]] 14:01, 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. --[[User:Isilkor\|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.--[[User:Günther\|Günther]] 15:57, 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. --[[User:Clonk-Karl\|Clonk-Karl]] 00:23, 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. --[[User:Clonk-Karl\|Clonk-Karl]] 00:23, 5 August 2009 (UTC)

← Older revision		Revision as of 14:01, 5 August 2009
Line 19:		Line 19:
	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. --[[User:Günther\|Günther]] 16:41, 4 August 2009 (UTC)		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. --[[User:Günther\|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. --[[User:Isilkor\|Isilkor]] 17:35, 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. --[[User:Isilkor\|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. --[[User:Günther\|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. --[[User:Isilkor\|Isilkor]] 14:01, 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. --[[User:Clonk-Karl\|Clonk-Karl]] 00:23, 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. --[[User:Clonk-Karl\|Clonk-Karl]] 00:23, 5 August 2009 (UTC)