Comment puis-je modifier la Javadoc quand je modifie quelqu'un d'autre code?

Je suis en train de travailler sur quelqu'un d'autre code et de faire d'importantes modifications. (Je suis la conversion à utiliser une base de données différent de celui qu'il a utilisé.) Comment dois-je indiquer dans la Javadoc des commentaires que je ne suis pas l'auteur original du code, mais que j'ai fait faire des contributions. Est-il propre ou standard façon de le faire déjà? Mes recherches sur Google ne m'aide à comprendre cela.

Exemple:

/**
* This class does some really awesome stuff.
* 
* @author Steph the Great - Modified to use PostgreSQL instead of Derby;
*         added comments to the code
*/

Aussi, je ne sais pas l'origine du nom de l'auteur, donc tout ce que je peux mettre bas, c'est moi . . .

  • Je ne serais pas trop stressé. Si vous pensez qu'il est important de différencier le travail de l'auteur original, vous pouvez utiliser les commentaires en ligne pour mettre en valeur vos modifications ou simplement à ajouter un commentaire à la javadoc de dire certains, comme "Modifié <date> faire ... par ..." ou tout ce que vous désirez. En général, les gens seulement s'énerver sur les changements apportés au code, si quelqu'un fait et il n'a pas de commentaires, donc l'étiquetage de l'auteur original, comme un mauvais programmeur. Aussi longtemps que vous ajoutez quelque chose à dire, vous l'avez modifié et ne sont pas l'auteur original, vous devriez être bien. Et dans beaucoup de cas, il n'a pas d'importance si vous n'avez pas 🙂
InformationsquelleAutor Steph | 2011-06-17
  1. 33

    Ces commentaires n'appartiennent pas à la javadoc 🙂 La javadoc doit expliquer le contrat, c'est ce que sont extraites et affichées dans l'auto-générée "documentation". Le reste sont juste des commentaires ou, peut-être, mieux encore, dans ce cas, SCM entrées de journal et n'ont pas de place dans la javadoc!

    Je serait susceptible de laisser de l'auteur original, mais si vous voulez de crédit...

    ...voir la @l'auteur javadoc de référence et à la note qu'il peut être inclus plusieurs fois. Cette section se rapporte explicitement à plusieurs auteurs et de commande, etc.

    /**
* This class does some really awesome stuff.
* It uses PostreSQL. 
*
* @author Steph the Great
* @author Freddy Four Fingers
*/
//DEC2012 - Fred - Modified to use PostgreSQL instead of Derby (but really, use SCM!)
class Awesome { ... }

    Heureux de codage.

    Notes sur la question un peu sans rapport avec exemple dans le post... si l'auteur n'est pas connu, alors plusieurs choses peuvent être faites. D'abord et avant tout ajouter un lien ou une référence à l'endroit où la source d'origine a été obtenue -- une option "je n'ai pas écrit cela à l'origine" pour plus de clarté peut être noté que bien.

    Ensuite, selon votre préférence:

    1. Ne spécifiez pas un @author domaine-pas toi-même. Il n'est pas nécessaire.
    2. Ajouter vous-même comme le seul auteur; la source d'origine est mentionné ci-dessus dans la javadoc
    3. Ajouter un mannequin auteur et à vous-même que la part de l'auteur, par exemple, @author Unknown @author unascribed (voir les commentaires et @l'auteur).
    4. Faire ce que vous voulez dans les termes de la licence, le cas échéant.
    • Eh bien, l'autre problème est que je ne connais pas l'auteur original, parce qu'il n'a pas écrit un seul commentaire dans son code. Je me sentirais bizarre juste de mettre mon nom en tant que l'auteur, bien que, depuis, il devrait ressembler à je prenait tout son crédit. Pensez-vous que je devrais juste omettre mon nom propre et n'ont pas d'auteurs cités? Je ne peux pas décider quelle est la meilleure approche serait ici.
    • +1 pour "Ces commentaires ne relèvent pas de la javadoc." Je impitoyablement supprimer @author tags dans notre base de code: ils n'ajoutent aucune valeur au-delà de ce que nous avons déjà dans notre système de contrôle de source, et en fait ils ont des négative de la valeur dès qu'ils sortent de la date.
    • les balises sont bons pour déterminer à qui revient la faute, si il y a des "questions" sur le code. 😉
    • Bouffon-Jeunes: Non, c'est ce que svn blame (ou l'équivalent dans votre choix SCM) est pour.
    • edit.) Lorsque l'auteur est inconnu, la norme de l'espace réservé nom est "unascribed". Voir oracle.com/technetwork/java/javase/documentation/... pour plus de détails.
    • Bouffon-Jeune, Grâce, mis à jour.
    • Si vous ne connaissez pas l'auteur original, comment savez-vous que vous êtes autorisé à modifier le code? En n'indiquant pas la paternité n'est pas l'équivalent dans le domaine public, que vous devriez connaître.
    • Ebermann: Le code appartient à l'entreprise pour laquelle je travaille et a été écrit par quelqu'un qui a l'habitude de travailler ici. Je ne suis pas voler quoi que ce soit.

    InformationsquelleAutor
  2. 10

    Vous pouvez avoir plus d'un @author tag. Donc, si vous avez apporté d'importants changements à une classe, il suffit d'ajouter une nouvelle @author avec le tag avec votre propre nom. Il n'y a pas besoin de la liste des changements que vous avez fait---l'historique de la révision devrait montrer que assez bien.

    • Ok. Je me sens bizarre de mettre mon nom en tant qu'auteur, je ne sais pas le nom du gars qui a écrit cette origine et ne peut pas le mettre vers le bas aussi bien. Il se sent comme je vais prendre le crédit pour son code.
    • Dans ce cas, mettre @author unascribed d'abord, puis d'ajouter votre propre @author tag. "Unascribed" est le nom standard utilisé lorsque l'auteur est inconnu. (Le nombre de classes dans le JDK, datant de la 1.0 ou jours plus tôt, ont @author unascribed. Juste pour le fun, Google pour l'auteur de "l'unascribed". :-))
    • D'accord, parfait. Merci beaucoup!
    InformationsquelleAutor Chris Jester-Young