Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > C Programming > C style: private functions, function docstrings & style

Reply
Thread Tools

C style: private functions, function docstrings & style

 
 
Ben Pfaff
Guest
Posts: n/a
 
      12-07-2007
Flash Gordon <(E-Mail Removed)> writes:

> Ben Pfaff wrote, On 07/12/07 04:50:
>> Jack Klein <(E-Mail Removed)> writes:
>>
>>> You seem to be missing the point that the doxygen documentation is
>>> generated from comment blocks in the source and header files, and if

>
> <snip>
>
>> Probably, I am overstating the case. If the doxygen
>> documentation is written with great care, and kept up to date as
>> code changes, I can see that it would be useful. I do not doubt
>> that on a team that you or a number of other comp.lang.c regulars
>> were on or led, this could be the case. But in the cases where
>> I've encountered it, the doxygen documentation by itself is
>> insufficient to understand how to properly use a library, and
>> I've always had to resort to the source code itself.

>
> Yes, I believe you are overstating the case. Your argument would apply
> just as well to all documentation and comments in code, since comments
> and documentation are only ever of use if they reflect the code
> reasonably well. Doxygen documentation relies on the developers
> writing it and keeping it up to date just as any other documentation
> and comments in the code.


Other documentation and comments in code is not usually ripped
bodily from the code and presented as a separate document. Thus,
it is easy to sanity-check it and read between the lines by
looking at the code that is nearby.
--
"...what folly I commit, I dedicate to you."
--William Shakespeare, _Troilus and Cressida_
 
Reply With Quote
 
 
 
 
Flash Gordon
Guest
Posts: n/a
 
      12-07-2007
Ben Pfaff wrote, On 07/12/07 21:11:
> Flash Gordon <(E-Mail Removed)> writes:
>
>> Ben Pfaff wrote, On 07/12/07 04:50:
>>> Jack Klein <(E-Mail Removed)> writes:
>>>
>>>> You seem to be missing the point that the doxygen documentation is
>>>> generated from comment blocks in the source and header files, and if

>> <snip>
>>
>>> Probably, I am overstating the case. If the doxygen
>>> documentation is written with great care, and kept up to date as
>>> code changes, I can see that it would be useful. I do not doubt
>>> that on a team that you or a number of other comp.lang.c regulars
>>> were on or led, this could be the case. But in the cases where
>>> I've encountered it, the doxygen documentation by itself is
>>> insufficient to understand how to properly use a library, and
>>> I've always had to resort to the source code itself.

>> Yes, I believe you are overstating the case. Your argument would apply
>> just as well to all documentation and comments in code, since comments
>> and documentation are only ever of use if they reflect the code
>> reasonably well. Doxygen documentation relies on the developers
>> writing it and keeping it up to date just as any other documentation
>> and comments in the code.

>
> Other documentation and comments in code is not usually ripped
> bodily from the code and presented as a separate document. Thus,
> it is easy to sanity-check it and read between the lines by
> looking at the code that is nearby.


Other documentation is often written before anyone considers writing a
single line of code. Requirement specifications, design specifications,
interface specifications, sometimes testing documentation etc. Also as
others have pointed out it is difficult to include graphics in a source
file. Also some people are not allowed to see the source code (because
it is not open source) or because they are doing true black-box testing
etc. In any case, as I already pointed out else-thread, if it is set up
appropriately the extracted documentation is NOT isolated from the code,
because you can have links from the documentation to the relevant
sections of the code.
--
Flash Gordon
 
Reply With Quote
 
 
 
 
Tor Rustad
Guest
Posts: n/a
 
      12-09-2007
Ben Pfaff wrote:
> Mark Bluemel <(E-Mail Removed)> writes:
>
>> Khookie wrote:
>>> I've been dev'ing in C for the past few months, and was wondering
>>> whether there was a standard coding style for [snip] documenting
>>> functions

>> Perhaps doxygen?

>
> Is doxygen documentation ever useful? I've read through lots of
> doxygen-generated documentation, but I was always left with
> numerous questions that could only be answered by looking at the
> source. Given that, I usually prefer to use something like
> "tags" to jump directly to function definitions. If the function
> has a comment at the top explaining its purpose, then that's more
> convenient than looking at a separate document describing its
> purpose, and the source code is right there to answer any
> remaining


Somewhat similar points that Jack makes, I started using doxygen some
5-6 years ago, and have not really used the tool to it's full potential
yet, but rather used it in a way to structure comments that I anyway
would have written.

My last programming project was very XP like, the time limits where
extremely short, and the functional specs a disaster. In order to reach
delivery dates, both top-down and bottom-up programming strategies where
used (just like drilling a tunnel from both ends, and hope the two teams
link up in the middle).

Some test cases where skipped, each given a '\test' tag, where shortcuts
could be taken, a '\todo' tag was inserted, in rare cases, known bugs
was left in with a '\bug' tag. The delivery date was met, before the day
fines started running. For phase 2, we will have far better time, and
can address all those shortcuts being made. Sure we could have used
another method or documenting tool, but it was easy and efficient.

I find it an advantage, to have documentation close to the source, and
it shouldn't be necessary to read the source to interface a library API
correctly. Doxygen can generate the docs in a number of formats, and by
including the dot package, you also get those awesome looking graphs.

--
Tor <(E-Mail Removed) | tr i-za-h a-z>
 
Reply With Quote
 
Tor Rustad
Guest
Posts: n/a
 
      12-09-2007
Khookie wrote:
> Hi everyone
>
> I've been dev'ing in C for the past few months, and was wondering
> whether there was a standard coding style for private functions
> (function/s not defined in the header file) and documenting functions
> (should this be done in the header or C file, and is there a
> standard?)


doxygen is commonly used for documenting

> For example: to make a function private in Python, you prefix the name
> with two underscores. Python also provides a functionality called
> docstrings to write doco for functions.


In C, we use *static* functions for this.

> I'm looking for a generally accepted style... primarily so that I can
> be a good C citizen & so the next developer doesn't want to kill
> me


Look up the indent tool, here you find some common styles, including GNU
and K&R. The Linux kernel use this style:

indent -npro -kr -i8 -ts8 -sob -l80 -ss -ncs

> And also, do any C developers here use camel case (popular in C#/Java)
> in their day to day C coding? I notice most code in C using plenty of
> underscores, so I've been keeping with that. IMHO, I prefer the look
> of camel case though.
>
> E.g. Camel case = socketDescriptor vs. underscores = socket_descriptor


In my expierence, application programmers often use long names e.g.
"SocketDescriptor", while low-level programmers use short'er names with
underscore.


--
Tor <(E-Mail Removed) | tr i-za-h a-z>
 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
Replacing a private function an keeping access to private variables Gregor Kofler Javascript 6 06-27-2008 10:24 PM
docstrings style question Steve Brown Python 11 01-11-2008 02:44 AM
Public Data in Private Class or Private Data in Public Class? DaveLessnau C++ 3 05-16-2005 06:53 PM
Need help with Style conversion from Style object to Style key/value collection. Ken Varn ASP .Net Building Controls 0 04-26-2004 07:06 PM
Should 'public virtual' always become 'private virtual'? & using private inheritance qazmlp C++ 19 02-04-2004 12:37 AM



Advertisments