[Pharo-project] Open Source and Constraints | Documentation is King
Well written: http://kennethreitz.org/open-source-and-constraints.html I also find that writing documentation (minimal method/class comments or longer standalone documents) improves coding, because you take another perspective. I wouldn't value it above tests though. Sven -- Sven Van Caekenberghe http://stfx.eu Smalltalk is the Red Pill
On 2 December 2012 18:57, Sven Van Caekenberghe <sven@stfx.eu> wrote:
Well written:
http://kennethreitz.org/open-source-and-constraints.html
I also find that writing documentation (minimal method/class comments or longer standalone documents) improves coding, because you take another perspective. I wouldn't value it above tests though.
"I'm designing an API and experience for myself and others as developers." That's exactly why I write tests in the first place: you write the tests to design the API. And hopefully the tests serve as good examples of how to use the API. (If they aren't good examples, you're writing your tests wrongly.) frank
Sven
-- Sven Van Caekenberghe http://stfx.eu Smalltalk is the Red Pill
Comments are ***REEEAALLLLY*** important because they help a guy reading the code to say yes you are smart and you got it right I will explain you why. Even writing comment in test is cool. Stef
Well written:
http://kennethreitz.org/open-source-and-constraints.html
I also find that writing documentation (minimal method/class comments or longer standalone documents) improves coding, because you take another perspective. I wouldn't value it above tests though.
Sven
-- Sven Van Caekenberghe http://stfx.eu Smalltalk is the Red Pill
But I think we do agree ;-) What makes me value tests a bit above documentation (but not so much that I am saying that documentation is not important), are two things: - tests are machine enforceable/controllable - you can find them exactly using senders or references On 04 Dec 2012, at 12:49, Stéphane Ducasse <stephane.ducasse@inria.fr> wrote:
Comments are ***REEEAALLLLY*** important because they help a guy reading the code to say yes you are smart and you got it right I will explain you why.
Even writing comment in test is cool.
Stef
Well written:
http://kennethreitz.org/open-source-and-constraints.html
I also find that writing documentation (minimal method/class comments or longer standalone documents) improves coding, because you take another perspective. I wouldn't value it above tests though.
Sven
-- Sven Van Caekenberghe http://stfx.eu Smalltalk is the Red Pill
I am fully for automating whatever can be automated. In this sense tests are a good combination of: * automated quality-control * sample-code Often there is no good way, for somebody new to a codebase, to distinguish between these two kinds of tests. There are tests that can be looked at like "runnable specifications" or "sample usage code". And there are tests that more about the nuts and bolts of a framework. Relevant to developers/maintainers of a package, but not for a potential user (yet). Solutions for this? Maybe categorizing tests accordingly... ? Either through packages/method-categories, or pragmas? I am also glad whenever I find an "example" method-category for a core class in a package. My 2 cents. 2012/12/4 Sven Van Caekenberghe <sven@stfx.eu>:
What makes me value tests a bit above documentation (but not so much that I am saying that documentation is not important), are two things:
- tests are machine enforceable/controllable - you can find them exactly using senders or references
On 4 December 2012 12:57, Sven Van Caekenberghe <sven@stfx.eu> wrote:
But I think we do agree ;-)
What makes me value tests a bit above documentation (but not so much that I am saying that documentation is not important), are two things:
- tests are machine enforceable/controllable - you can find them exactly using senders or references
well, a test is more direct and concise way of telling how your stuff works (or should work), as well as serving as a source of example. what you write in a test, could take like 10 times more explaining same in docs. still. with tests you cannot tell: - why it is done like that - what are responsibilities of components and how you can change/replace them if needed. - what is best/recommended practices to use your software - where the starting/entry point. -- Best regards, Igor Stasenko.
On Dec 4, 2012, at 12:57 PM, Sven Van Caekenberghe wrote:
But I think we do agree ;-)
What makes me value tests a bit above documentation (but not so much that I am saying that documentation is not important), are two things:
- tests are machine enforceable/controllable - you can find them exactly using senders or references
sure I still want somebody to help with <testForDocumentation> idea. so that some tests are added to the documentation of package Stef
On 04 Dec 2012, at 12:49, Stéphane Ducasse <stephane.ducasse@inria.fr> wrote:
Comments are ***REEEAALLLLY*** important because they help a guy reading the code to say yes you are smart and you got it right I will explain you why.
Even writing comment in test is cool.
Stef
Well written:
http://kennethreitz.org/open-source-and-constraints.html
I also find that writing documentation (minimal method/class comments or longer standalone documents) improves coding, because you take another perspective. I wouldn't value it above tests though.
Sven
-- Sven Van Caekenberghe http://stfx.eu Smalltalk is the Red Pill
2012/12/4 Stéphane Ducasse <stephane.ducasse@inria.fr>:
Comments are ***REEEAALLLLY*** important because they help a guy reading the code to say "yes, you are smart and you got it right"
+1 Never thought about it that way... documentation as a confirmation of what is intuitive...
On 04.12.2012 12:49, Stéphane Ducasse wrote:
Comments are ***REEEAALLLLY*** important because they help a guy reading the code to say yes you are smart and you got it right I will explain you why.
Even writing comment in test is cool.
Stef I would go so far as to say comments in tests are *especially* important. It's sometimes hard to tell whether a failure is due to a faulty test, or an actual bug, when you have no idea (even when looking at the code) what case the test was actually written to cover. With a comment of what the test was intended to do, you have a better feel for how to handle it.
TL;DR: Intent, while obvious to whoever is writing the test, may not be so clear to whoever is around when it starts failing. Cheers, Henry
On Tue, Dec 4, 2012 at 6:30 AM, Henrik Sperre Johansen < henrik.s.johansen@veloxit.no> wrote:
On 04.12.2012 12:49, Stéphane Ducasse wrote:
Comments are ***REEEAALLLLY*** important because they help a guy reading the code to say yes you are smart and you got it right I will explain you why.
Even writing comment in test is cool.
Stef
I would go so far as to say comments in tests are *especially* important. It's sometimes hard to tell whether a failure is due to a faulty test, or an actual bug, when you have no idea (even when looking at the code) what case the test was actually written to cover. With a comment of what the test was intended to do, you have a better feel for how to handle it.
True, to a point. As long as later coders that alter the method/class/package either adhear to the original comments, or update the comments when they change the behaviour/intent of the code, or at the very least, delete the comment when they make significant changes that would invalidate the comment, this is true. If, on the other hand, the comments are left as is while potentially drastic changes are made, then the comments become seriously misleading. Not to say comments are bad - but we must all work to make sure the comments that exist stay relevant. -Chris
On Dec 4, 2012, at 7:45 PM, Chris Cunningham <cunningham.cb@gmail.com> wrote:
On Tue, Dec 4, 2012 at 6:30 AM, Henrik Sperre Johansen <henrik.s.johansen@veloxit.no> wrote: On 04.12.2012 12:49, Stéphane Ducasse wrote: Comments are ***REEEAALLLLY*** important because they help a guy reading the code to say yes you are smart and you got it right I will explain you why.
Even writing comment in test is cool.
Stef I would go so far as to say comments in tests are *especially* important. It's sometimes hard to tell whether a failure is due to a faulty test, or an actual bug, when you have no idea (even when looking at the code) what case the test was actually written to cover. With a comment of what the test was intended to do, you have a better feel for how to handle it. True, to a point. As long as later coders that alter the method/class/package either adhear to the original comments, or update the comments when they change the behaviour/intent of the code, or at the very least, delete the comment when they make significant changes that would invalidate the comment, this is true. If, on the other hand, the comments are left as is while potentially drastic changes are made, then the comments become seriously misleading.
Not to say comments are bad - but we must all work to make sure the comments that exist stay relevant.
And of course it is important to actually change comments when someone finds a problem. "How can you change the world if you can't even change a typo in a comment?" Marcus
I would go so far as to say comments in tests are *especially* important. It's sometimes hard to tell whether a failure is due to a faulty test, or an actual bug, when you have no idea (even when looking at the code) what case the test was actually written to cover. With a comment of what the test was intended to do, you have a better feel for how to handle it.
TL;DR: Intent, while obvious to whoever is writing the test, may not be so clear to whoever is around when it starts failing.
Cheers, Henry
+1
participants (8)
-
Chris Cunningham -
Frank Shearar -
Henrik Sperre Johansen -
Igor Stasenko -
Marcus Denker -
Sebastian Nozzi -
Stéphane Ducasse -
Sven Van Caekenberghe