Documentation de référence

Dans l’édition de novembre de MSDN Magazine, Peter Gruenbaum explique comment écrire une bonne documentation de référence pour les APIs dans sont article intitulé “A Coder’s Guide to Writing API Documentation”.

Mon attention s’est particulièrement portée sur la Figure 2 et 3, qui explique comment commenter tout en gardant une homogénéité au travers de tout l’API. Je vous les ai reproduit ici:

Figure 2 Reference Documentation Style

Type Guideline Examples
Class Start with a word like “Represents” “Represents a user’s photo album.”
Methods and functions Start with a verb “Returns the number of contacts for the specified area.”

“Pauses the video.”
Properties Use a noun or start with verbs such as “Gets” or “Gets and sets” “The user’s tasks.”

“Gets and sets a collection of the user’s tasks.”
Events Start with a phrase such as “Raised when” or “Occurs when” “Raised when the response from server is received.”
XML elements Use a noun-based phrase “The city’s postal code.”
Boolean values For Boolean properties, start with “Indicates whether”; for Boolean return values on methods and functions, start with “Returns whether” “Indicates whether the control is visible.”

“Returns whether two regions intersect.”

Figure 3 Reference Documentation Example

[Lire]
MSDN  MSDN Magazine  Peter Gruenbaum  API  Commentaires  Documentation 

De retour du Népal

Après 4 semaines de vacances, me voici maintenant de retour à la maison. Il faut dire que ce n’est pas nécessairement des vacances de tout repos que de se rendre à l’autre bout du monde et de se rendre au pied du sommet le plus haut au monde!

4 semaines sans contact avec un ordinateur (ok ok, 2 minutes pour dire que l’on était encore vivant), cela fait plutôt étrange! Et saviez-vous que tout le long de la montée vers le camp de base de l’Everest ils ont implanté des antennes cellulaires? Donc pas étonnant que de croiser un Sherpa en pleine discussion avec son portable!

[Lire]
Népal  Everest  Vacances 

[VS2010 Tips] Insertion multi-lignes

En lisant l’article de MSDN permettant de convertir des applications VBA en C# 4.0, je me suis rappelé la fameuse fonction ALT+[Sélection] permettant d’insérer le même texte/code sur plusieurs ligne à la fois. Alors, voici la version française de cette partie de l’article:

Appuyer sur ALT et sélectionner l’endroit ou vous désirez insérez votre code (sélection en bleu pâle dans l’image ci-dessous:
image
Tapez votre code et boom! Toutes les sélectionnés ont été remplis de votre code:

[Lire]
VBA  MSDN  VS2010  Tips  Visual Studio 2010  C#