Author: Heiner Marxen
Date: 11:08:40 06/08/05
Go up one level in this thread
On June 08, 2005 at 06:29:49, Tord Romstad wrote: >Hi Dann and William, > >First of all, thanks a lot to both of you for your input! Some comments >below. > >On June 07, 2005 at 19:52:28, William Hoggarth wrote: >> >>On June 07, 2005 at 19:28:13, Dann Corbit wrote: >>> >>>So if you add comments, they absolutely, positively must stay in sync with the >>>code or they introduce a serious defect. >> >>Keeping comments in step with the code really isn't very hard at all. > >Sounds easy in theory, but I have found that it is not quite that easy in >practise. When looking at other people's code, it seems that I am not the >only one who has problems with this. When rewriting a chunk of code, it >is very easy to forget to inspect the surrounding comments and check that >they remain correct and relevant. I agree. >There is also another reason I don't like having a lot of comments in my >code: I find it much easier to read code when I can see as many lines of >code as possible without moving my eyes around or scrolling up and down. >Comments therefore often actually *reduce* the readability of the code, >in my eyes. For similar reasons, I usually don't have a lot of vertical >whitespace in my code. I agree completely. >There are cases when a chunk of code is so hard to read that a comment >explaining what is going on would improve the readability, but in such >cases I think the need of a comment should be viewed as an indication >that the code is badly written. Good code should be self-documenting >and understandable with just a few comments. While true most of the time, it is just a rule, i.e. there are exceptions. In Chest there is one such example, where I had to add a comment block, since I didn't understand the code any more... but the code was ok, it is still exactly the correct code. Several speed-up ideas are combined there, so the matter itself is non-trivial. >>>Probably you mean: >>> >>>Side ^= 1; >>> >>>>switch_sides(Side) >>> >>>or they are not equivalent, unless they are both the object of an assignment. >> >>Sorry, it was a typo on my part. >> >>>>The second is a lot more readable and both will compile to the same code >>>>(assuming you've set up the macro right). >>> >>>Both seem equally clear to me. >> >>Yes they would to an experienced Chess programmer, but that's not the kind of >>person I am talking about. That example is quite a simple one too. Things like >>(from<<7)|(type<<17) are more cryptic. > >I tend to agree with William here. This is not only about readability, >but also about abstraction and flexibility. Using macros and inline >functions instead of spelling out the low-level details every time makes >it easier to change the data structures later. Again, I agree. The main point is not readability, but rather abstraction and flexibility. Yes. >I mostly try to use macros or functions for this kind of stuff. That is >why I have definitions like this: > >#define FriendlyPawn (PAWN|(Side<<3)) > >There is no doubt, however, that in many cases I have been too lazy about >this. I should try to clean this up and use more such macros in future >versions. > >By the way, does anybody have a good suggestion for a name for a macro which >takes a piece type and colour as input, and produces a piece? The macro >would look like this: > >#define PieceOfTypeAndColour(type,colour) ((type)|((colour)<<3)) > >This would be useful many places in my program. It would also make it >possible to redefine the FriendlyPawn macro above as: > >#define FriendlyPawn PieceOfTypeAndColour(PAWN, Side) > >I think the name PieceOfTypeAndColour is too long and cryptic, though. >Better suggestions are welcome. Too long: yes, maybe. Cryptic? Huh? If this is the only way to construct a Piece (i.e. always from Type and Colour), you could reduce the name to just: #define PieceOf(type,colour) ((type)|((colour)<<3)) or maybe: #define PieceOfTC(type,colour) ((type)|((colour)<<3)) with "TC" being a short reminder of which argument comes first. >>>Never use macros for functions. They are not type safe, and can have evil, >>>unexpected side effects that are different from a function call because of the >>>sequence point. >>> >>>Inline functions are the same speed as macros. > >Unfortunately this is not always the case. Gcc, for instance, does not >support inlining of functions defined in a different source file. Yes, unfortunately, inline function come with some danger being inefficient. > I still >agree that inline functions are generally preferable, of course. I try >to use macros only when a function would not work, or when the expression(s) >contained are very simple. Personally I still adhere to the habit of using macros... maybe mostly because I'm used to them for so long. >>These were my thoughts on what I think would help. I know they would help me >>and they tie in with what I have read is good practice. > >Yes, your help is highly appreciated! :-) > >Tord In general I think one should make up ones mind for what level of expertise one writes the comments. I tend to not target the beginner level audience, but rather the advanced reader, who would not be scared by expressions mixing "<<", "|" and other bit operators. And probably foremost... I write all those comments for myself (to read later). Cheers, Heiner
This page took 0 seconds to execute
Last modified: Thu, 15 Apr 21 08:11:13 -0700
Current Computer Chess Club Forums at Talkchess. This site by Sean Mintz.