Lignes horizontales dans les commentaires

Question

Je me rends compte que cela dépend en grande partie des préférences personnelles, mais je suis curieux de savoir s'il y a des inconvénients évidents à ce qui suit; Je trouve que je divise constamment le code source en groupes logiques (via "comments") dans le même fichier. Par exemple:

---

//---------------------------------------------------------------------------- 
#include "..." 
//---------------------------------------------------------------------------- 
#include <...> 
//---------------------------------------------------------------------------- 
#include <boost/...> 
//---------------------------------------------------------------------------- 
#include <os-specific/...> 
//---------------------------------------------------------------------------- 
namespace 
{ 
    void Foo() 
    { 
    } 
} 
//---------------------------------------------------------------------------- 
namespace 
{ 
    void Bar() 
    { 
    } 
} 
//---------------------------------------------------------------------------- 
namespace 
{ 
    void Baz() 
    { 
    } 
} 
//---------------------------------------------------------------------------- 
int main() 
{ 
} 
//---------------------------------------------------------------------------- 
//This file ends with a new-line. 

Ou:

//---------------------------------------------------------------------------- 
#ifndef FOO_HEADER_INCLUDED 
#define FOO_HEADER_INCLUDED 
//---------------------------------------------------------------------------- 
#include "..." 
//---------------------------------------------------------------------------- 
namespace Foo 
{ 
    void Bar(); 
} 
//---------------------------------------------------------------------------- 
#endif 
//---------------------------------------------------------------------------- 
//This file ends with a new-line. 

---

J'ai lu par une source étrangère récemment et je l'ai remarqué que pratiquement personne ne fait cela. Le seul argument que je pourrais proposer contre ce genre de "division" est quand vous imprimez physiquement le code source en mode portrait où vos diviseurs (si plus de ~ 80 caractères) seront encapsulés. C'est un non-problème en mode paysage, cependant.

Pour être honnête, je ne sais même pas pourquoi ou quand j'ai commencé à le faire. Y a-t-il d'autres inconvénients à ce TOC?

En outre, pour moi, ce genre de comportement est agnostique langage; J'écrivais un script shell l'autre jour et j'ai remarqué le même comportement.

Answer 1

J'avais l'habitude de faire quelque chose comme ça il y a longtemps. J'aurais des en-têtes de section pour le bloc d'inclusions, de déclarations, de fonctions, et ainsi de suite.

Il y a quelques raisons que je QUITTER le faire:

1. Il est une chose à maintenir. Vous devez vous souvenir de les ajouter lorsque vous écrivez un nouveau code et de les retirer lorsque vous supprimez des éléments. Je préfère dépenser l'effort mental sur le code lui-même, sans être obsédé par le fait de savoir si quelque chose est assez grand pour justifier une pause ou non.

2. Certaines choses défiaient la classification facile. Supposons que vous souhaitiez imbriquer une petite classe dans une fonction. Allez-vous vraiment ajouter une ligne comme celle-ci au milieu de votre fonction?

3. Les éditeurs plus intelligents facilitaient la navigation dans le code. À l'origine, ils étaient une sorte de bonnes terres lorsque vous faites défiler un fichier pour trouver des choses. Mais dans Emacs, je passe beaucoup de temps avec des recherches incrémentales et des fichiers de tags. Et dans les occasions où j'utilise un IDE, il me montre les morceaux du fichier sur le côté et laisse-moi leur sauter dessus en un clic.Comme je me suis amélioré, je suis passé à des modules plus petits, moins monolithiques. Ces jours-ci, je vais simplement déplacer des éléments dans un nouveau fichier plutôt que d'ajouter une nouvelle section à un fichier source existant. Les fichiers eux-mêmes fournissent le groupement logique. Chaque fichier est une unité soudée et cohérente - pourquoi le briser? Je suis passé à l'utilisation de commentaires de style Javadoc/Doxygen de manière cohérente. Ceux-ci sont plus descriptifs que les lignes horizontales aléatoires, et je suis également arrivé à trouver qu'ils ont l'air beaucoup plus agréable dans le code, aussi.

Answer 2

Il me semble que vous n'utilisez pas un bon IDE. Par exemple, vous pouvez utiliser #regions dans VS pour grouper votre code. Et c'est beaucoup plus facile que vos méthodes.

Answer 3

Certains d'entre nous les utilisent, mais peut-être pas aussi généreusement que vous. Voir ma réponse au this question.

Answer 4

Les régions sont un bien meilleur moyen de répartir le code. L'entreprise que je suis maintenant a une politique contre "flowerboxing" (I.E. entourant les choses avec/***** et ****/commentaires) et je suis sûr que cela s'applique aussi aux barres horizontales. Je voudrais coller avec les régions, rend les choses beaucoup plus agréables.

Answer 5

Dans les fichiers source C, j'ai un modèle qui divise les fichiers en sections telles que #defines, typedefs, statique (fichier entier) définitions des variables et des prototypes de fonction, les fonctions publiques et les fonctions statiques, etc. (De même pour les fichiers d'en-tête C). Ceux-ci sont délimités par une ligne de '='.

Contrairement à la question ci-dessus, celles-ci ne sont pas créées afin de regrouper les blocs de code existants. I commencer avec ces sections, car il fournit une structure utile pour chaque fichier, et dicte où placer le code que je crée.

J'ai également une ligne de '-' entre chaque fonction, et parfois entre les groupes logiques dans d'autres sections si nécessaire.

Si rien d'autre, je trouve utile de pouvoir voir où les fonctions commencent et se terminent lors du défilement du fichier.