On 13/01/2014 06:47 PM, clipka wrote:

> There is one major advantage in "commenting" your code by structuring it
> and choosing good identifiers, rather than placing comments in there:
> Comments are typically more prone to become outdated over time.

This is another of the major themes of the book. Inaccurate comments are 
arguably *worse* than no comments at all.

> (Provided of course that the code is produced and maintained in an
> environment where refactoring is encouraged. If the policy is "try to
> avoid touching any of the existing code", it is easier to fix a comment
> that has become obsolete, rather than a once-good identifier that no
> longer matches what the function or variable does.)

One of the things that frustrates me about my job is that I want to 
refactor things, and people complain that it would take too long and so 
we won't do it.

Obviously the customers aren't going to be too impressed if we spent 2 
years restructuring the codebase with no user-visible change in 
functionality. But that doesn't mean that *all* refactoring should be 
put off...

Post a reply to this message

Le 2014-01-12 05:38, Orchid Win7 v1 a écrit :
>
> I don't have the book in front of me now, but prime number sieving is
> actually one of the examples. They even go so far as to remove the "stop
> searching after sqrt(max)" optimisation to "make the code simpler".
> Because most of the time, being able to understand the code is far more
> important than getting maximum performance out of it.

If you do leave it in, *that* is worthy of a comment.  Not every 
programmer will be good enough with math to figure out why you don't 
need to check for factors > sqrt(max).


-- 
/*Francois Labreque*/#local a=x+y;#local b=x+a;#local c=a+b;#macro P(F//
/*    flabreque    */L)polygon{5,F,F+z,L+z,L,F pigment{rgb 9}}#end union
/*        @        */{P(0,a)P(a,b)P(b,c)P(2*a,2*b)P(2*b,b+c)P(b+c,<2,3>)
/*   gmail.com     */}camera{orthographic location<6,1.25,-6>look_at a }

Post a reply to this message

On 13/01/2014 09:36 PM, Francois Labreque wrote:
> Le 2014-01-12 05:38, Orchid Win7 v1 a écrit :
>>
>> I don't have the book in front of me now, but prime number sieving is
>> actually one of the examples. They even go so far as to remove the "stop
>> searching after sqrt(max)" optimisation to "make the code simpler".
>> Because most of the time, being able to understand the code is far more
>> important than getting maximum performance out of it.
>
> If you do leave it in, *that* is worthy of a comment. Not every
> programmer will be good enough with math to figure out why you don't
> need to check for factors > sqrt(max).

I agree. That's the sort of thing that's sufficiently non-obvious that 
it ought to be explained somewhere.

Then again, how many programs sieve prime numbers? Most software seems 
to just push database records from A to B and back again...

Post a reply to this message

On 13-1-2014 19:19, clipka wrote:
> Am 13.01.2014 11:19, schrieb andrel:
>> On 13-1-2014 0:56, clipka wrote:
>>> Am 12.01.2014 22:21, schrieb andrel:
>>>
>>
>>> As for a function's name, I find it very important that it denotes not
>>> /how/ the function does something, nor just /what/ it does, but also
>>> with what /intention/.
>>>
>> True, but this is a general case where the point is that there are still
>> several ways to do things. More specific names are needed lower in the
>> tree.
>> In this case I would go for something like:
>>
>> ECG=ComputeECGfromTiming(Timing,VolumeConductionModel,ElectricalModel,
>> Parameters);
>>
>> or simply
>>
>> ECG=ComputeECGfromTiming(Timing,ForwardModel);
>
> Sounds like a very good choice to me.
>

Well, luckily I am not the one that decides.
OTOH I am sort of forced to use it even if it is IMO unsuitable for 
research purposes. Perhaps you can understand now some of the reasons why.
One day I might just stand up and give a short introduction on 
programming. Which will probably be the end of the cooperation.


-- 
Everytime the IT department forbids something that a researcher deems
necessary for her work there will be another hole in the firewall.

Post a reply to this message

On 13-1-2014 21:00, Orchid Win7 v1 wrote:
> On 13/01/2014 06:47 PM, clipka wrote:
>
>> There is one major advantage in "commenting" your code by structuring it
>> and choosing good identifiers, rather than placing comments in there:
>> Comments are typically more prone to become outdated over time.
>
> This is another of the major themes of the book. Inaccurate comments are
> arguably *worse* than no comments at all.
>
>> (Provided of course that the code is produced and maintained in an
>> environment where refactoring is encouraged. If the policy is "try to
>> avoid touching any of the existing code", it is easier to fix a comment
>> that has become obsolete, rather than a once-good identifier that no
>> longer matches what the function or variable does.)
>
> One of the things that frustrates me about my job is that I want to
> refactor things, and people complain that it would take too long and so
> we won't do it.
>
> Obviously the customers aren't going to be too impressed if we spent 2
> years restructuring the codebase with no user-visible change in
> functionality. But that doesn't mean that *all* refactoring should be
> put off...

When I was working with a colleague we sometimes split. One did all the 
interaction with users and the other did the cleanup in a branch.
Now I am just by myself I need to do it incrementally, which does not 
work, because I do too many things already. But basically you should 
think of it as on-the-fly-garbage-collection. (With the disadvantage 
that you first need to cleanup and rewrite to support that)

-- 
Everytime the IT department forbids something that a researcher deems
necessary for her work there will be another hole in the firewall.

Post a reply to this message

On 13-1-2014 23:04, Orchid Win7 v1 wrote:
> On 13/01/2014 09:36 PM, Francois Labreque wrote:
>> Le 2014-01-12 05:38, Orchid Win7 v1 a écrit :
>>>
>>> I don't have the book in front of me now, but prime number sieving is
>>> actually one of the examples. They even go so far as to remove the "stop
>>> searching after sqrt(max)" optimisation to "make the code simpler".
>>> Because most of the time, being able to understand the code is far more
>>> important than getting maximum performance out of it.
>>
>> If you do leave it in, *that* is worthy of a comment. Not every
>> programmer will be good enough with math to figure out why you don't
>> need to check for factors > sqrt(max).
>
> I agree. That's the sort of thing that's sufficiently non-obvious that
> it ought to be explained somewhere.
>
> Then again, how many programs sieve prime numbers? Most software seems
> to just push database records from A to B and back again...

Depends on your field of work ;) I don't.

-- 
Everytime the IT department forbids something that a researcher deems
necessary for her work there will be another hole in the firewall.

Post a reply to this message

Am 13.01.2014 21:00, schrieb Orchid Win7 v1:

> One of the things that frustrates me about my job is that I want to
> refactor things, and people complain that it would take too long and so
> we won't do it.
>
> Obviously the customers aren't going to be too impressed if we spent 2
> years restructuring the codebase with no user-visible change in
> functionality. But that doesn't mean that *all* refactoring should be
> put off...

Remember that refactoring is not the same as rewriting. Refactoring - at 
least as I understand it - is a sequence of many small baby steps. 
Ideally, the steps should be small enough that you can formally prove 
that they don't change functionality in any way. Such as moving some 
portion of code into a separate function. Or making a public member 
variable protected and providing getter and setter functions for access. 
Or renaming a function.

Each such step is a separate refactoring action, so it shouldn't be too 
difficult to interweave it with your daily job.

Make it a habit to always be a bit more invasive than necessary whenever 
you need to make a change, so that further modifications in that same 
portion of code will be easier.

Make it a habit to set aside, say, two days per month for refactoring work.

Explain to your boss why you're doing this, in terms he can understand: 
You're investing time to improve overall code quality, in order to save 
more time in the future.

Also tell your boss that this is the kind of smart thinking he hired you 
for.

And to stay on good terms with your colleagues, make it clear to them, 
your boss, and also to yourself, that it is your /personal/ desire to 
improve the overall code quality, and that it's ok for you if your 
colleagues don't join in the effort.

Post a reply to this message

>> One of the things that frustrates me about my job is that I want to
>> refactor things, and people complain that it would take too long and so
>> we won't do it.
>>
>> Obviously the customers aren't going to be too impressed if we spent 2
>> years restructuring the codebase with no user-visible change in
>> functionality. But that doesn't mean that *all* refactoring should be
>> put off...
>
> Remember that refactoring is not the same as rewriting. Refactoring - at
> least as I understand it - is a sequence of many small baby steps.
> Ideally, the steps should be small enough that you can formally prove
> that they don't change functionality in any way. Such as moving some
> portion of code into a separate function. Or making a public member
> variable protected and providing getter and setter functions for access.
> Or renaming a function.
>
> Each such step is a separate refactoring action, so it shouldn't be too
> difficult to interweave it with your daily job.

Another theme of the book. The author states that your goal should be to 
have the class fully covered in unit tests, and each change must keep 
all the unit tests working.

Suffice it to say, changing code in a way that doesn't break existing 
stuff is far, far harder than just throwing the lot in the bin and 
starting again.

The other Fun Thing is that there are subsystems which are used 
*everywhere*. Some of them have awful design, we all know it's awful, 
but if you changed it, you would have to touch every client of that 
subsystem - i.e., the entire application. For this reason, we never make 
any improvements to these systems.

I personally am of the opinion that it would be *that* damned hard to 
change all the code; there are automated refactoring tools and such to 
help you do it. But it seems I am in the minority...

Post a reply to this message

> One
> aspect is about visual perception: In your version, the reader has to
> first figure out what is code and what is explanation, whereas in Andy's
> version it's one and the same.

Except Andy's version doesn't actually have any code, it's hidden away 
in a separate method (which you would either need to search or scroll to).

Especially with comments being highlighted in most code editors, I 
personally find this much more useful:

prime = array[0]; // get next prime

thank this:

prime = GetNextPrime(array);

What seems to be being advocated is to replace source code like this:

<trivial code> <comment>

with this:

<call a function with "comment" name>
...
<function definition of "comment">
  <trivial code>
</>

Sorry I don't see the benefit.

Post a reply to this message

Am 15.01.2014 10:57, schrieb scott:
>> One
>> aspect is about visual perception: In your version, the reader has to
>> first figure out what is code and what is explanation, whereas in Andy's
>> version it's one and the same.
>
> Except Andy's version doesn't actually have any code, it's hidden away
> in a separate method (which you would either need to search or scroll to).

... if I'd really bother. Which is exactly the point: Usually I won't.

> Especially with comments being highlighted in most code editors, I
> personally find this much more useful:
>
> prime = array[0]; // get next prime
>
> thank this:
>
> prime = GetNextPrime(array);

Whoever invented code highlighting does indeed deserve a medal or two.

Typically though, comments are actually "lowlighted"; while it does make 
it easier to distinguish between code and comments, it still draws the 
attention to the code rather than the comments.


> What seems to be being advocated is to replace source code like this:
>
> <trivial code> <comment>
>
> with this:
>
> <call a function with "comment" name>
> ...
> <function definition of "comment">
>   <trivial code>
> </>
>
> Sorry I don't see the benefit.

As I said, visual perception is only one aspect.

I also don't think the single-line case is typical in practice.

Then there's also the aspect that if you move into functions some 
multi-line code sections operating at array access level, it can be 
argued that the remaining single-line code sections operating at array 
access level should be moved into functions as well, in order to get a 
homogenous level of abstraction.

And last not least, I'm not really advocating the above - I just present 
arguments in favor (which probably sounds/reads just the same, but 
actually isn't). I prefer to leave it up to the reader to decide for 
themselves.

Post a reply to this message