On Jan 27, 2011, at 10:07 AM, Tudor Girba wrote:
Hi Stef,
I think your mail can easily be misunderstood to say that Filesystem is crap and that the authors did a bad job. I believe your intention was simply to push people to write more comments and give Filesystem as an example of a fine system that does not have comments :).
Exact :)
Filesystem is a nice piece of work and the authors did a good job.
yes
I understand that there are no comments, but the documentation found on Lukas' website provides a better overview than most class comments in Pharo: http://www.lukas-renggli.ch/blog/filesystem-1 http://www.lukas-renggli.ch/blog/filesystem-2
So, why not just copy these into the help system?
This is not a solution. This would be a workaround. This is incomplete and missing important information. Then we should also review some api like workingDirectory returning a path. I started to write important class comments like DO NOT USE subclasses of FSDisk.... directly. Let FSDiskFilesystem returns the current filesystem. FSPath is for internal framework use. That I learned the hard way = spending 5 times more time than expected to do something. Documentation is not a by product. Finally I started to reorganize the package because there is no point directing people to **I want a comment for every single method.** I hate a system that tells me in permanence that I'm an idiot because what is written is not obvious to me. Sorry to be stubborn but I will not move on micrometer on that. ****Code without documentation and comments does not exist*** If the community wants a better filesystem then we should have comments in FS. Since I want it I will slowly and painfully try to understand that I'm idiot because I do not understand and reverse engineer what could have been written up front. I will slowly do it since there is no other paths. But I guess that you understand my deep state of mind. Stef