[chbot] Lazy software developers please read... chocolate fish

[Chris Hamling]

Two solutions,

First, comment your code as you write it. Preferably before you write it,
that is what we train good programmers to do. A comment that is just a
rehash of code is worthless and does nothing to help people understand the
code.

Second, avoid linux ;-)

Chris

-----Original Message-----
From: chchrobotics-bounces at lists.linuxnut.co.nz
[mailto:chchrobotics-bounces at lists.linuxnut.co.nz] On Behalf Of Andre Renaud
Sent: Thursday, 7 August 2014 10:44 a.m.
To: Christchurch Robotics
Subject: Re: [chbot] Lazy software developers please read... chocolate fish

> Yes I know all that, have done this regularly in gawk (because I found 
> that easier than to do the same thing in sed). Never said you couldn't 
> do it in sed, given a mental challenge, too much time, or both. But 
> I'll give you all a chocolate fish at the next meeting if you show a 
> sed program like
>     sed 's/xxx/yyy/'
> as suggested, that does do the job as asked, for a whole .c and a 
> whole .h file. I'm even being generous and allow you multiple 's' 
> commands, not as suggested.

Obviously it'd be nice to have a fully generic solution that covers all of
your code, no matter what style you write it in. However assuming you're
working on a single code base, and it's all been written in a single style,
then it often isn't too hard to match lines that look like function
prototypes. For instance, I tend to write all function prototypes like this:
static int linked_list_move_to_end(linked_list_t *list, linked_node_t *node)

It starts in column 1 (or 0, depending on what editor you use), there aren't
line breaks between return types and function name, or between function name
and the first argument (although there may be some after that, if there are
a lot of arguments).

So for me, the following does a pretty good first pass at shoving a template
Doxygen header above every function:
sed 's,\(^[a-z].*(\),\n/**\n * Doxygen template\n */\n\1,g' FILE.c

Given the idea is simply to take some of the labour intensiveness out of
putting the documentation in, it doesn't have to be perfect as you're
obviously going to be going into each file by hand later on anyway to put in
sensible values, so if it misses the odd function, or adds an entry in where
it shouldn't be, removing those oddities is less work than adding in the
bulk of typical cases.

Regards,
Andre

_______________________________________________
Chchrobotics mailing list Chchrobotics at lists.linuxnut.co.nz
http://lists.ourshack.com/mailman/listinfo/chchrobotics
Mail Archives: http://lists.ourshack.com/pipermail/chchrobotics/
Web site: http://kiwibots.org
Meetings 3rd Monday each month.

When replying, please edit your Subject line to reflect new content.