Smalltalk › Pharo › Pharo Smalltalk Developers

Open Source and Constraints | Documentation is King

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

12 messages Options

Sven Van Caekenberghe-2

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

Frank Shearar-3

Re: Open Source and Constraints | Documentation is King

On 2 December 2012 18:57, Sven Van Caekenberghe <[hidden email]> 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
>
>

Stéphane Ducasse

Re: Open Source and Constraints | Documentation is King

In reply to this post by Sven Van Caekenberghe-2

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
>
>

Sven Van Caekenberghe-2

Re: Open Source and Constraints | Documentation is King

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 <[hidden email]> 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
>>
>

senTalker

Re: Open Source and Constraints | Documentation is King

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 <[hidden email]>:
> 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

senTalker

Re: Open Source and Constraints | Documentation is King

In reply to this post by Stéphane Ducasse

2012/12/4 Stéphane Ducasse <[hidden email]>:
> 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...

Henrik Sperre Johansen

Re: Open Source and Constraints | Documentation is King

In reply to this post by Stéphane Ducasse

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

cbc

Re: Open Source and Constraints | Documentation is King

On Tue, Dec 4, 2012 at 6:30 AM, Henrik Sperre Johansen <[hidden email]> 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

Marcus Denker-4

Re: Open Source and Constraints | Documentation is King

On Dec 4, 2012, at 7:45 PM, Chris Cunningham <[hidden email]> wrote:

On Tue, Dec 4, 2012 at 6:30 AM, Henrik Sperre Johansen <[hidden email]> 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

Igor Stasenko

Re: Open Source and Constraints | Documentation is King

In reply to this post by Sven Van Caekenberghe-2

On 4 December 2012 12:57, Sven Van Caekenberghe <[hidden email]> 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.

Stéphane Ducasse

Re: Open Source and Constraints | Documentation is King

In reply to this post by Sven Van Caekenberghe-2

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 <[hidden email]> 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
>>>
>>
>
>

Stéphane Ducasse

Re: Open Source and Constraints | Documentation is King

In reply to this post by Henrik Sperre Johansen

>
> 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

>