Only the Code Tells the Truth - Revision history

Kevlin at 15:34, 3 July 2009

Kevlin — Fri, 03 Jul 2009 15:34:35 GMT

←Older revision		Revision as of 15:34, 3 July 2009
Line 1:		Line 1:
-	The ultimate semantics of a program is given by the running code. If this is in binary form, it ~~might not~~ be ~~easily~~ read~~. However, the~~ source code should be available if it is your program. Looking at the source code the meaning of the program should be apparent, ~~since this is~~ the ~~only relevant thing to look~~ at. Even the most accurate requirements document does not tell the whole truth~~, since it~~ does not contain the detailed story of what the program is actually doing, only the high-level intentions of the requirements analyst. A design document may capture a planned design, but it will lack the necessary detail of the implementation ~~and~~ may have lost ~~its link~~ with the current implementation. ~~Furthermore, these documents~~ may ~~never~~ have been written in the first place~~, or may have been lost by the time the code needs to be changed in the future~~. The code may be the only thing left.	+	The ultimate semantics of a program is given by the running code. If this is in binary form only, it will be a difficult read! The source code should, however, be available if it is your program, any typical commercial software development, an open source project, or code in a dynamically interpreted language. Looking at the source code, the meaning of the program should be apparent. To know what a program does, the source is ultimately all you can be sure of looking at. Even the most accurate requirements document does not tell the whole truth: It does not contain the detailed story of what the program is actually doing, only the high-level intentions of the requirements analyst. A design document may capture a planned design, but it will lack the necessary detail of the implementation. These documents may have lost their synchronization with the current implementation... or may simply have been lost. Or never written in the first place. The source code may be the only thing left.

-	~~Ask yourself~~, how clearly is your code telling you or any other programmer what it is doing?	+	With this in mind, ask yourself how clearly is your code telling you or any other programmer what it is doing?

-	You might say, "Oh, my comments will tell". But keep in mind that comments are not running code. They can be just as wrong as other forms of documentation. There has been a tradition saying comments are unconditionally a good thing, so some ~~naive~~ programmers ~~started to~~ write more and more comments, even explaining trivia ~~that is said by~~ the code ~~to a professional programmer~~. ~~That~~ is wrong. If your code needs comments, consider refactoring it so it doesn't. Lengthy comments can clutter screen space and might even be hidden automatically by your IDE. If you need to explain a change, do so in the version control system check-in message and not in the code.	+	You might say, "Oh, my comments will tell you everything you need to know." But keep in mind that comments are not running code. They can be just as wrong as other forms of documentation. There has been a tradition saying comments are unconditionally a good thing, so unquestioningly some programmers write more and more comments, even restating and explaining trivia already obvious in the code. This is the wrong way to clarify your code. If your code needs comments, consider refactoring it so it doesn't. Lengthy comments can clutter screen space and might even be hidden automatically by your IDE. If you need to explain a change, do so in the version control system check-in message and not in the code.

-	What can you do to actually make your code tell the truth as clearly as possible? Strive for good ~~naming of program elements~~. Structure your code with respect to cohesive functionality, which also eases naming. Decouple your code to achieve orthogonality. Write automated tests explaining the intended behaviour and check the interfaces. Refactor mercilessly when you learn how to code a simpler, better solution. Make your code as simple as possible to read and understand.	+	What can you do to actually make your code tell the truth as clearly as possible? Strive for good names. Structure your code with respect to cohesive functionality, which also eases naming. Decouple your code to achieve orthogonality. Write automated tests explaining the intended behaviour and check the interfaces. Refactor mercilessly when you learn how to code a simpler, better solution. Make your code as simple as possible to read and understand.

-	Treat your code like any other composition, such as a poem, an essay, a public blog, or an important email. ~~Carefully craft your expression~~, so that it does what it should and communicates as directly as possible what it is doing, so that it still communicates your intention when you are no longer around. Remember that useful code is used much longer than ever intended. Maintenance programmers will thank you. And, if you are a maintenance programmer and the code you are working on does not tell the truth easily, apply the guidelines above in a proactive manner. Establish some sanity in the code and keep your own sanity.	+	Treat your code like any other composition, such as a poem, an essay, a public blog, or an important email. Craft what you express carefully, so that it does what it should and communicates as directly as possible what it is doing, so that it still communicates your intention when you are no longer around. Remember that useful code is used much longer than ever intended. Maintenance programmers will thank you. And, if you are a maintenance programmer and the code you are working on does not tell the truth easily, apply the guidelines above in a proactive manner. Establish some sanity in the code and keep your own sanity.

Kevlin: Only the Code tells the Truth moved to Only the Code Tells the Truth

Kevlin — Fri, 03 Jul 2009 15:13:09 GMT

Only the Code tells the Truth moved to Only the Code Tells the Truth

←Older revision

Revision as of 15:13, 3 July 2009

PeterSommerlad at 13:11, 16 October 2008

PeterSommerlad — Thu, 16 Oct 2008 13:11:17 GMT

←Older revision		Revision as of 13:11, 16 October 2008
Line 1:		Line 1:
-	The ultimate ~~meaning~~ of a program is given by the running code. If this is in binary form, it might not be easily read. However, the source code should be available if it is your program. Looking at the source code the meaning of the program should be apparent, since this is the only relevant thing to look at. Even the most accurate requirements document does not tell the whole truth, since it does not contain the detailed story of what the program is actually doing, only the high-level intentions of the requirements analyst. A design document may capture a planned design, but it will lack the necessary detail of the implementation and may have lost its link with the current implementation. Furthermore, these documents may never have been written in the first place, or may have been lost by the time the code needs to be changed in the future. The code may be the only thing left.	+	The ultimate semantics of a program is given by the running code. If this is in binary form, it might not be easily read. However, the source code should be available if it is your program. Looking at the source code the meaning of the program should be apparent, since this is the only relevant thing to look at. Even the most accurate requirements document does not tell the whole truth, since it does not contain the detailed story of what the program is actually doing, only the high-level intentions of the requirements analyst. A design document may capture a planned design, but it will lack the necessary detail of the implementation and may have lost its link with the current implementation. Furthermore, these documents may never have been written in the first place, or may have been lost by the time the code needs to be changed in the future. The code may be the only thing left.

	Ask yourself, how clearly is your code telling you or any other programmer what it is doing?		Ask yourself, how clearly is your code telling you or any other programmer what it is doing?

Kevlin at 15:33, 15 October 2008

Kevlin — Wed, 15 Oct 2008 15:33:25 GMT

←Older revision		Revision as of 15:33, 15 October 2008
Line 1:		Line 1:
-	The ultimate meaning of a program is given by the running code. If this is in binary form, it might not be easily read. However, the source code should be available if it is your program. Looking at the source code the meaning of the program ~~is told~~, since this is the only relevant thing to look at. Even the most accurate requirements document does not tell the whole truth, since it does not contain the detailed story of what the program is actually doing, only the high-level intentions of the requirements analyst. A design document may capture ~~the~~ planned design, but it will lack the necessary detail of the implementation and may have lost its link with the current implementation. Furthermore, these documents may never have been written in the first place, or may be lost ~~when your~~ code needs to be changed in the future. The code may be the only thing left.	+	The ultimate meaning of a program is given by the running code. If this is in binary form, it might not be easily read. However, the source code should be available if it is your program. Looking at the source code the meaning of the program should be apparent, since this is the only relevant thing to look at. Even the most accurate requirements document does not tell the whole truth, since it does not contain the detailed story of what the program is actually doing, only the high-level intentions of the requirements analyst. A design document may capture a planned design, but it will lack the necessary detail of the implementation and may have lost its link with the current implementation. Furthermore, these documents may never have been written in the first place, or may have been lost by the time the code needs to be changed in the future. The code may be the only thing left.

	Ask yourself, how clearly is your code telling you or any other programmer what it is doing?		Ask yourself, how clearly is your code telling you or any other programmer what it is doing?
Line 7:		Line 7:
	What can you do to actually make your code tell the truth as clearly as possible? Strive for good naming of program elements. Structure your code with respect to cohesive functionality, which also eases naming. Decouple your code to achieve orthogonality. Write automated tests explaining the intended behaviour and check the interfaces. Refactor mercilessly when you learn how to code a simpler, better solution. Make your code as simple as possible to read and understand.		What can you do to actually make your code tell the truth as clearly as possible? Strive for good naming of program elements. Structure your code with respect to cohesive functionality, which also eases naming. Decouple your code to achieve orthogonality. Write automated tests explaining the intended behaviour and check the interfaces. Refactor mercilessly when you learn how to code a simpler, better solution. Make your code as simple as possible to read and understand.

-	Treat your code like a poem or an essay, ~~or, like~~ a public blog or an important email. Carefully craft your expression, so that it does what it should and communicates as directly as possible what it is doing, so that it still communicates your intention when you are no longer around. Remember that useful code is used much longer than ever intended. Maintenance programmers will thank you. And, if you are a maintenance programmer and the code you are working on does not tell the truth easily, apply the guidelines above in a proactive manner. Establish some sanity in the code and keep your own sanity.	+	Treat your code like any other composition, such as a poem, an essay, a public blog, or an important email. Carefully craft your expression, so that it does what it should and communicates as directly as possible what it is doing, so that it still communicates your intention when you are no longer around. Remember that useful code is used much longer than ever intended. Maintenance programmers will thank you. And, if you are a maintenance programmer and the code you are working on does not tell the truth easily, apply the guidelines above in a proactive manner. Establish some sanity in the code and keep your own sanity.

PeterSommerlad at 14:47, 15 October 2008

PeterSommerlad — Wed, 15 Oct 2008 14:47:24 GMT

←Older revision		Revision as of 14:47, 15 October 2008
Line 1:		Line 1:
-	The ultimate meaning of a program is given by the running code. If this is in binary form, it might not be easily read. However, the source code should be available if it is your program. Looking at the source code the meaning of the program is told, since this is the only relevant thing to look at. Even the ~~best~~ requirements document does not tell the whole truth, since it does not contain the detailed story of what the program is actually doing, only the high-level intentions of the requirements analyst. A design document may capture the planned design, but it will lack the necessary detail of the implementation and may have lost its link with the current implementation. Furthermore, these documents may never have been written in the first place, or may be lost when your code needs to be changed in the future. The code may be the only thing left.	+	The ultimate meaning of a program is given by the running code. If this is in binary form, it might not be easily read. However, the source code should be available if it is your program. Looking at the source code the meaning of the program is told, since this is the only relevant thing to look at. Even the most accurate requirements document does not tell the whole truth, since it does not contain the detailed story of what the program is actually doing, only the high-level intentions of the requirements analyst. A design document may capture the planned design, but it will lack the necessary detail of the implementation and may have lost its link with the current implementation. Furthermore, these documents may never have been written in the first place, or may be lost when your code needs to be changed in the future. The code may be the only thing left.

	Ask yourself, how clearly is your code telling you or any other programmer what it is doing?		Ask yourself, how clearly is your code telling you or any other programmer what it is doing?

PeterSommerlad at 14:46, 15 October 2008

PeterSommerlad — Wed, 15 Oct 2008 14:46:51 GMT

←Older revision		Revision as of 14:46, 15 October 2008
Line 3:		Line 3:
	Ask yourself, how clearly is your code telling you or any other programmer what it is doing?		Ask yourself, how clearly is your code telling you or any other programmer what it is doing?

-	You might say, "Oh, my comments will tell". But keep in mind that comments are not running code. They can be just as wrong as other forms of documentation. There has been a tradition saying comments are unconditionally a good thing, so some naive programmers started to write more and more comments, even explaining trivia that is said by the code to a professional programmer. That is wrong. If your code needs comments, consider refactoring it so it doesn't. Lengthy comments can clutter screen space and might even be hidden automatically by your IDE.	+	You might say, "Oh, my comments will tell". But keep in mind that comments are not running code. They can be just as wrong as other forms of documentation. There has been a tradition saying comments are unconditionally a good thing, so some naive programmers started to write more and more comments, even explaining trivia that is said by the code to a professional programmer. That is wrong. If your code needs comments, consider refactoring it so it doesn't. Lengthy comments can clutter screen space and might even be hidden automatically by your IDE. If you need to explain a change, do so in the version control system check-in message and not in the code.

	What can you do to actually make your code tell the truth as clearly as possible? Strive for good naming of program elements. Structure your code with respect to cohesive functionality, which also eases naming. Decouple your code to achieve orthogonality. Write automated tests explaining the intended behaviour and check the interfaces. Refactor mercilessly when you learn how to code a simpler, better solution. Make your code as simple as possible to read and understand.		What can you do to actually make your code tell the truth as clearly as possible? Strive for good naming of program elements. Structure your code with respect to cohesive functionality, which also eases naming. Decouple your code to achieve orthogonality. Write automated tests explaining the intended behaviour and check the interfaces. Refactor mercilessly when you learn how to code a simpler, better solution. Make your code as simple as possible to read and understand.

PeterSommerlad at 14:44, 15 October 2008

PeterSommerlad — Wed, 15 Oct 2008 14:44:23 GMT

←Older revision		Revision as of 14:44, 15 October 2008
Line 1:		Line 1:
-	The ultimate meaning of a program is given by the running code. If this is in binary form, it might not be easily read. However, the source code should be available if it is your program. Looking at the source code the meaning of the program is told, since this is the only relevant thing to look at. Even the best requirements document does not tell the whole truth, since it does not contain the detailed story of what the program is actually doing, only the high-level intentions of the requirements analyst. A design document may capture the planned design, but it will lack the necessary detail of the implementation and may have lost its link with the current implementation. Furthermore, these documents may never have been written in the first place, or may ~~have~~ lost when your code needs to be changed in the future. The code may be the only thing left.	+	The ultimate meaning of a program is given by the running code. If this is in binary form, it might not be easily read. However, the source code should be available if it is your program. Looking at the source code the meaning of the program is told, since this is the only relevant thing to look at. Even the best requirements document does not tell the whole truth, since it does not contain the detailed story of what the program is actually doing, only the high-level intentions of the requirements analyst. A design document may capture the planned design, but it will lack the necessary detail of the implementation and may have lost its link with the current implementation. Furthermore, these documents may never have been written in the first place, or may be lost when your code needs to be changed in the future. The code may be the only thing left.

	Ask yourself, how clearly is your code telling you or any other programmer what it is doing?		Ask yourself, how clearly is your code telling you or any other programmer what it is doing?
Line 7:		Line 7:
	What can you do to actually make your code tell the truth as clearly as possible? Strive for good naming of program elements. Structure your code with respect to cohesive functionality, which also eases naming. Decouple your code to achieve orthogonality. Write automated tests explaining the intended behaviour and check the interfaces. Refactor mercilessly when you learn how to code a simpler, better solution. Make your code as simple as possible to read and understand.		What can you do to actually make your code tell the truth as clearly as possible? Strive for good naming of program elements. Structure your code with respect to cohesive functionality, which also eases naming. Decouple your code to achieve orthogonality. Write automated tests explaining the intended behaviour and check the interfaces. Refactor mercilessly when you learn how to code a simpler, better solution. Make your code as simple as possible to read and understand.

-	Treat your code like a poem or an essay. Carefully craft your expression, so that it does what it should and communicates as directly as possible what it is doing, so that it still communicates your intention when you are no longer around. Remember that useful code is used much longer than ever intended. Maintenance programmers will thank you. And, if you are a maintenance programmer and the code you are working on does not tell the truth easily, apply the guidelines above in a proactive manner. Establish some sanity in the code and keep your own sanity.	+	Treat your code like a poem or an essay, or, like a public blog or an important email. Carefully craft your expression, so that it does what it should and communicates as directly as possible what it is doing, so that it still communicates your intention when you are no longer around. Remember that useful code is used much longer than ever intended. Maintenance programmers will thank you. And, if you are a maintenance programmer and the code you are working on does not tell the truth easily, apply the guidelines above in a proactive manner. Establish some sanity in the code and keep your own sanity.

Kevlin at 09:52, 15 October 2008

Kevlin — Wed, 15 Oct 2008 09:52:03 GMT

←Older revision		Revision as of 09:52, 15 October 2008
Line 1:		Line 1:
-	The ultimate meaning of a program is given by the running code. If this is in binary form, it might not be easily read. However, the source code should be available if it is your program. Looking at the source code the meaning of the program is told, since this is the only relevant thing to look at. ~~The nicest~~ requirements document ~~is always lying~~, since it does not contain the ~~true~~ story of what the program is actually doing, only the intentions of the requirements analyst. A design document ~~can~~ capture the planned design, but ~~might~~ have lost its link with the current implementation. ~~All~~ these documents ~~might~~ never have been written, or ~~are~~ lost when your code needs to be changed in the future. The only thing left ~~actually might be only the code~~.	+	The ultimate meaning of a program is given by the running code. If this is in binary form, it might not be easily read. However, the source code should be available if it is your program. Looking at the source code the meaning of the program is told, since this is the only relevant thing to look at. Even the best requirements document does not tell the whole truth, since it does not contain the detailed story of what the program is actually doing, only the high-level intentions of the requirements analyst. A design document may capture the planned design, but it will lack the necessary detail of the implementation and may have lost its link with the current implementation. Furthermore, these documents may never have been written in the first place, or may have lost when your code needs to be changed in the future. The code may be the only thing left.

-	Ask yourself, is your code telling you or any other programmer what it is doing?	+	Ask yourself, how clearly is your code telling you or any other programmer what it is doing?

-	You might say, "Oh my comments will tell". ~~Please consider,~~ comments are not running code. They can be as wrong as ~~the~~ other ~~documents~~. There has been a tradition saying comments are good, so some naive programmers started to write more and more comments, even explaining trivia that is said by the code to a professional programmer. That is wrong. If your code needs comments, consider refactoring it so it doesn't. Lengthy comments can clutter screen space and might even be hidden automatically by your IDE.	+	You might say, "Oh, my comments will tell". But keep in mind that comments are not running code. They can be just as wrong as other forms of documentation. There has been a tradition saying comments are unconditionally a good thing, so some naive programmers started to write more and more comments, even explaining trivia that is said by the code to a professional programmer. That is wrong. If your code needs comments, consider refactoring it so it doesn't. Lengthy comments can clutter screen space and might even be hidden automatically by your IDE.

-	What can you do to actually make your code tell the truth? Strive for good naming of program elements! Structure your code with respect to cohesive functionality, which also eases naming~~! De-couple~~ your code to achieve orthogonality! Write automated tests explaining the intended behaviour and check the interfaces! Refactor mercilessly when you learn how to code a simpler, better solution! Make your code as simple as possible to read and understand!	+	What can you do to actually make your code tell the truth as clearly as possible? Strive for good naming of program elements. Structure your code with respect to cohesive functionality, which also eases naming. Decouple your code to achieve orthogonality. Write automated tests explaining the intended behaviour and check the interfaces. Refactor mercilessly when you learn how to code a simpler, better solution. Make your code as simple as possible to read and understand.

-	Treat your code like a poem or an essay. Carefully craft your expression, so that it does what it should and ~~actually tells a professional developer like you~~ what it is doing, ~~even~~ when you are ~~not or~~ no longer around. Remember, useful code is used much longer than ever intended. ~~Your maintenance~~ programmers will thank you. ~~Don't forget~~, if you are ~~the~~ maintenance programmer and the code you~~'ve got is~~ not ~~easily telling~~ the truth, apply the guidelines above in a ~~pro-active~~ manner~~, to establish~~ sanity of the code and keep your own sanity.	+	Treat your code like a poem or an essay. Carefully craft your expression, so that it does what it should and communicates as directly as possible what it is doing, so that it still communicates your intention when you are no longer around. Remember that useful code is used much longer than ever intended. Maintenance programmers will thank you. And, if you are a maintenance programmer and the code you are working on does not tell the truth easily, apply the guidelines above in a proactive manner. Establish some sanity in the code and keep your own sanity.

PeterSommerlad at 09:03, 13 October 2008

PeterSommerlad — Mon, 13 Oct 2008 09:03:43 GMT

←Older revision		Revision as of 09:03, 13 October 2008
Line 3:		Line 3:
	Ask yourself, is your code telling you or any other programmer what it is doing?		Ask yourself, is your code telling you or any other programmer what it is doing?

-	You might say, "Oh my comments will tell". Please consider, comments are not running code. They can be as wrong as the other documents. There has been a tradition saying comments are good, so some naive programmers started to write more and more comments, even explaining trivia that is said by the code to a professional programmer. That is wrong.	+	You might say, "Oh my comments will tell". Please consider, comments are not running code. They can be as wrong as the other documents. There has been a tradition saying comments are good, so some naive programmers started to write more and more comments, even explaining trivia that is said by the code to a professional programmer. That is wrong. If your code needs comments, consider refactoring it so it doesn't. Lengthy comments can clutter screen space and might even be hidden automatically by your IDE.

	What can you do to actually make your code tell the truth? Strive for good naming of program elements! Structure your code with respect to cohesive functionality, which also eases naming! De-couple your code to achieve orthogonality! Write automated tests explaining the intended behaviour and check the interfaces! Refactor mercilessly when you learn how to code a simpler, better solution! Make your code as simple as possible to read and understand!		What can you do to actually make your code tell the truth? Strive for good naming of program elements! Structure your code with respect to cohesive functionality, which also eases naming! De-couple your code to achieve orthogonality! Write automated tests explaining the intended behaviour and check the interfaces! Refactor mercilessly when you learn how to code a simpler, better solution! Make your code as simple as possible to read and understand!

-	Treat your code like a poem or an essay. Carefully craft your expression, so that it does what it should and actually tells a professional developer like you what it is doing, even when you are not or no longer around. Remember, useful code is used much longer than ever intended.	+	Treat your code like a poem or an essay. Carefully craft your expression, so that it does what it should and actually tells a professional developer like you what it is doing, even when you are not or no longer around. Remember, useful code is used much longer than ever intended. Your maintenance programmers will thank you. Don't forget, if you are the maintenance programmer and the code you've got is not easily telling the truth, apply the guidelines above in a pro-active manner, to establish sanity of the code and keep your own sanity.

PeterSommerlad: New page: The ultimate meaning of a program is given by the running code. If this is in binary form, it might not be easily read. However, the source code should be available if it is your program. ...

PeterSommerlad — Mon, 13 Oct 2008 08:46:31 GMT

New page: The ultimate meaning of a program is given by the running code. If this is in binary form, it might not be easily read. However, the source code should be available if it is your program. ...

New page

The ultimate meaning of a program is given by the running code. If this is in binary form, it might not be easily read. However, the source code should be available if it is your program. Looking at the source code the meaning of the program is told, since this is the only relevant thing to look at. The nicest requirements document is always lying, since it does not contain the true story of what the program is actually doing, only the intentions of the requirements analyst. A design document can capture the planned design, but might have lost its link with the current implementation. All these documents might never have been written, or are lost when your code needs to be changed in the future. The only thing left actually might be only the code.

Ask yourself, is your code telling you or any other programmer what it is doing?

You might say, "Oh my comments will tell". Please consider, comments are not running code. They can be as wrong as the other documents. There has been a tradition saying comments are good, so some naive programmers started to write more and more comments, even explaining trivia that is said by the code to a professional programmer. That is wrong.

What can you do to actually make your code tell the truth? Strive for good naming of program elements! Structure your code with respect to cohesive functionality, which also eases naming! De-couple your code to achieve orthogonality! Write automated tests explaining the intended behaviour and check the interfaces! Refactor mercilessly when you learn how to code a simpler, better solution! Make your code as simple as possible to read and understand!

Treat your code like a poem or an essay. Carefully craft your expression, so that it does what it should and actually tells a professional developer like you what it is doing, even when you are not or no longer around. Remember, useful code is used much longer than ever intended.

by [[Peter Sommerlad]]

This work is licensed under a
[http://creativecommons.org/licenses/by/3.0/us/ Creative Commons Attribution 3]

Back to [[97 Things Every Programmer Should Know]] home page