En-tête du dossier ou commentaire général

Est-ce que quelqu'un a un bon commentaire de départ bien structuré pour un fichier? Je suis à la recherche de quelque chose qui a l'air sympa, que ce soit chic ou très professionnel.En-tête du dossier ou commentaire général

Par commentaire général, je veux dire le commentaire en haut d'un fichier montrant votre nom et votre but du fichier. Comme celui-ci:

/********************************************************   
    * hello -- program to print out "Hello World".   * 
    *              * 
    * Author: FirstName, LastName       * 
    *              * 
    * Purpose: Demonstration of a simple program.   * 
    *              * 
    * Usage:            * 
    *  Runs the program and the message appears.  * 
    ********************************************************/

Source

2009-11-21 user69514

Personnellement, je ne suis pas fan de ces choses. Je pense que les cases décrites dans les étoiles ressemblent à du code étudiant et ne font qu'ajouter au fouillis visuel. Par tous les moyens, expliquez ce qui se passe dans javadocs. Ne l'encombre pas. – duffymo

Je suppose que vous avez raison. Je ne veux pas vraiment ajouter beaucoup de choses, mais je voudrais toujours ajouter mon nom et quelques informations de base – user69514

+1 duffymo; ils sont fastidieux à maintenir (ce qui tend à signifier qu'ils ne sont pas maintenus et dérivent en décalage avec le code). Utilisez quelque chose de simple et simplifie la génération automatique de documents API (javadocs, doxygen, etc.) – SimonJ

Format doxygen?

/*! \file hello.cpp 
\brief program to print out "Hello World" 

Created: 2009-11-21 by FirstName, LastName \n 
Modified: \n 
*/

Source

2009-11-21 20:45:42

Je creuse ce format – user69514

Suis-je le seul qui pense que cela semble moche? Pourquoi avoir tout ce balisage quand la plupart des gens vont lire le code source brut de toute façon? SI vous devez vraiment utiliser un système comme celui-ci, essayez Natural Docs. – mk12

Pour C#, Stylecop applique un en-tête qui ressemble à ceci

// <copyright file="filename.cs" company="Company"> 
// Copyright (c) 2008 All Right Reserved 
// </copyright> 
// <author>Mr blah blah</author> 
// <email>[email protected]</email> 
// <date>2009-11-21</date> 
// <summary>File description.</summary>

Vous pouvez configurer le nom de l'entreprise requis dans la balise du droit d'auteur.

Source

2009-11-21 20:47:20

Pour Java, je préfère le style suivant (mais ces points peuvent être appliqués à d'autres langues):

Si vous souhaitez inclure des choses du droit d'auteur, faites dans les premiers une ou deux lignes . Soyez bref. Si vous avez quelque chose à ajouter à ce sujet, faites-le dans un fichier README ou sur le site Web de votre produit. Ne pas inclure de metainfo tel que nom de fichier, date de dernière modification, balises @author ou @version. Des outils comme Subversion peuvent mieux suivre ce genre de choses, et la duplication de ce type d'informations ajoute simplement du travail inutile pour les synchroniser.
Lancez le javadoc de votre classe avec une phrase qui résume sa fonction principale.
Pas besoin d'utiliser des légendes comme Purpose ou Usage, expliquez simplement ce que vous avez à dire en quelques paragraphes. Les formulaires et les champs sont parfaits si un script doit les traiter, mais pas si les gens les lisent.

Donc, pour résumer, j'utiliser quelque chose comme ceci:

/* Copyright 2002-2009 Foo Ltd. All rights reserved. */ 

package foo.bar; 

/** 
* This class does this or that. 
* 
* Now you can go into the details, try to be professional here by writing a 
* few clear, articulate paragraphs, not by drawing fancy ascii boxes. 
* 
* @see foo.bar.OtherClass 
*/ 
public class MyClass { 
    ... 
}

Source

2009-11-21 21:14:13 candiru

En-tête du dossier ou commentaire général

Répondre

Questions connexes