[GenABEL-dev] [Genabel-commits] r1429 - pkg/GenABEL/man

L.C. Karssen lennart at karssen.org
Fri Nov 29 11:14:42 CET 2013 

Good suggestions.


On 11/29/2013 10:54 AM, Maksim Struchalin wrote:
> Thanks you Lennart
> 
> So, I guess 80 lines should be a limit for PGC.Rd.
> 
> Two suggestions to the document:
> 1) I would add a recommendation to leave comments to the C/R code.
> Sometimes it is just impossible to understand what is some code for.

Very important! Good documentation (within the code) is extremely
important.

> 2) Add description at the head of to each file with code like.

A header is good. Some points:

- Version/revision number: I don't think it's a good idea to include a
version number/Revision number. That's what SVN is for. Otherwise you
need to update those all the time.

- author names: The problem with adding author names is that this can
grow a lot if more people work on it. Do we really want this kind of
bookkeeping? In principle you can look up in SVN who added what to which
file.

- Licence: as far as I understand officially/legally each file should
have the licence in the header (or at least mentioned). You see that in
many GPL programs.

- For C/C++ files: Maybe we should use Doxygen-style headers? That will
also help document the code (see my recent experiments with that in
ProbABEL).


Best,

Lennart.

> 
> For example, in every file with code I ever wrote I have a small
> description on the top like:
> 
> //#=====================================================================================
> //#
> //#       Filename:  gtps_container.h
> //#
> //#    Description:  Set of functions for merging two snp.data class objects.
> //#
> //#        Version:  1.0
> //#        Created:  18-March-2008
> //#       Revision:  none
> //#       
> //#
> //#         Author:  Maksim V. Struchalin, Yurii S. Aulchenko
> //#        Company:  ErasmusMC, Epidemiology & Biostatistics Department, The Netherlands.
> //#          Email:  m.struchalin@@erasmusmc.nl, i.aoultchenko at erasmusmc.nl
> //#
> //#=====================================================================================
> 
> 
> from which it is clear who wrote the file (person's name and contacts),
> when and for whom. This is convinient for other developers who is gonna
> edit this file in the future to address their quiestions directly to the
> person who wrote the original code.
> 
> best,
> Maksim
> 
> 
> On 29/11/2013 16:25, L.C. Karssen wrote:
>> Dear Maksim, Yakov, others,
>>
>> About coding style, please see the document on GenABEL coding standards
>> (work in progress) we created some time ago:
>> http://genabel.r-forge.r-project.org/codingstyle.html
>>
>> It would be great to have uniform coding in all of the GenABEL suite.
>>
>> By the way, suggestions for additions/corrections of the document are
>> welcome!
>>
>>
>> Lennart.
>>
>>
>>
>> On 11/29/2013 10:20 AM, Maksim Struchalin wrote:
>>> Hi Yakov,
>>>
>>> I made this change because when I run "R CMD check --as-cran ", I got a
>>> message:
>>> ______________________________________________
>>> * checking Rd line widths ... NOTE
>>> Rd file
>>> ‘/home/maksim/work/GenABEL_project/genabel/pkg/GenABEL.Rcheck/00_pkg_src/GenABEL/man/PGC.Rd’:
>>>
>>> \examples lines wider than 100 characters:
>>> #result=PGC(data=chi2.1df,method="group_regress",p=freq,df=1, pol.d=2,
>>> plot=TRUE, start.corr=FALSE,n_quiantile=3)
>>> ______________________________________________
>>>
>>> Here are guidlines how to write .Rd files
>>> (http://developer.r-project.org/Rds.html).
>>> If I were you, I would replace "result=PGC(d..." by "result<-PGC(d..."
>>> because using <- instead of = is common R rule for assignments.
>>>
>>> It recommends to keep the line length in .Rd file not more then 65
>>> characters but I guess this an old rule and now the limit is 100
>>> characters.
>>>
>>> best,
>>> Maksim
>>>
>>> On 28/11/2013 16:38, Yury Aulchenko wrote:
>>>> Yakov,
>>>>
>>>> please pay attention to this commit (I know that you were changing the
>>>> code of the GC procedures recently)
>>>>
>>>> YA
>>>>
>>>> On Nov 28, 2013, at 05:38 AM, noreply at r-forge.r-project.org wrote:
>>>>
>>>>> Author: maksim
>>>>> Date: 2013-11-28 05:38:54 +0100 (Thu, 28 Nov 2013)
>>>>> New Revision: 1429
>>>>>
>>>>> Modified:
>>>>>    pkg/GenABEL/man/PGC.Rd
>>>>> Log:
>>>>> Deleteted comments because R CMD check --as-cran said that these
>>>>> lines are wider than 100 characters and they will be truncated in the
>>>>> PDF manual. This should not have any influence on the code generated
>>>>> from it.
>>>>>
>>>>> Modified: pkg/GenABEL/man/PGC.Rd
>>>>> ===================================================================
>>>>> --- pkg/GenABEL/man/PGC.Rd    2013-11-28 04:21:29 UTC (rev 1428)
>>>>> +++ pkg/GenABEL/man/PGC.Rd    2013-11-28 04:38:54 UTC (rev 1429)
>>>>> @@ -63,8 +63,6 @@
>>>>> s <- summary(ge03d2)
>>>>> freq <- s$Q.2
>>>>> result=PGC(data=chi2.1df,method="median",p=freq,df=1, pol.d=2,
>>>>> plot=TRUE, lmax=1.1,start.corr=FALSE)
>>>>> -#"group_regress" is better to use when we have more than 50K SNPs
>>>>> -#result=PGC(data=chi2.1df,method="group_regress",p=freq,df=1,
>>>>> pol.d=2, plot=TRUE, start.corr=FALSE,n_quiantile=3)
>>>>> }
>>>>> \author{
>>>>>    Yakov Tsepilov
>>>>>
>>>>> _______________________________________________
>>>>> Genabel-commits mailing list
>>>>> Genabel-commits at lists.r-forge.r-project.org
>>>>> https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/genabel-commits
>>>>>
>>>> _______________________________________________
>>>> genabel-devel mailing list
>>>> genabel-devel at lists.r-forge.r-project.org
>>>> https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/genabel-devel
>>>>
>>> _______________________________________________
>>> genabel-devel mailing list
>>> genabel-devel at lists.r-forge.r-project.org
>>> https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/genabel-devel
>>
>>
>> _______________________________________________
>> genabel-devel mailing list
>> genabel-devel at lists.r-forge.r-project.org
>> https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/genabel-devel
> 
> 
> 
> _______________________________________________
> genabel-devel mailing list
> genabel-devel at lists.r-forge.r-project.org
> https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/genabel-devel
> 

-- 
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
L.C. Karssen
Utrecht
The Netherlands

lennart at karssen.org
http://blog.karssen.org
GPG key ID: A88F554A
-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 230 bytes
Desc: OpenPGP digital signature
URL: <http://lists.r-forge.r-project.org/pipermail/genabel-devel/attachments/20131129/7d6121ab/attachment.sig>

More information about the genabel-devel mailing list