|
From: Philippe W. <phi...@sk...> - 2015-04-21 21:01:51
|
On Mon, 2015-04-20 at 23:46 +0200, Florian Krohm wrote: > On 20.04.2015 23:28, Philippe Waroquiers wrote: > > Nice cleanup. > > One small comment: wouldn't the description of VG_(sr_as_string)() > > better be put in the .h rather than in the .c file ? > > The fact that the memory is static (or must be freed by the caller) > > is better described there ? > > I tend to favour small comments in header files and put noteworthy > details next to the implementation. But I have no strong feelings and we > don't have a policy for this either. So if you want to change it please > feel free. Done as revision 15127. At work, we have a convention/guideline that to know how to use a module, it is/should be sufficient to read the 'spec' (i.e. the .h) of the module. This allows to limit the reading to what is needed. E.g. allows to skip internal functions/comments/internal data structures and so on. So, information for the caller such as 'you must free the returned pointer' or 'returns a static buffer, overwritten on next invocation' is better placed in the .h, following this convention. I think many modules of Valgrind already follows this approach. Maybe we could be more systematic in that approach ? Philippe |