I commenti nella parte superiore di un file sorgente sono una cattiva idea? [duplicare]

1

Uso Xcode per modificare i miei file sorgente, e in genere un file sarà simile a questo

//
//  Queue.swift
//  SomeCompany
//
//  Created by Someone (Job Title) on 26/06/2017.
//  Copyright © 2017 SomeCompany. All rights reserved.
//

/// A queue is a list where you can only insert new items at the back and remove items from the front. 
/// This ensures that the first item you enqueue is also the first item you dequeue. 
/// First come, first serve!
struct Queue<T> {
    ...
}

I commenti in cima a un file sorgente sono una cattiva idea? Il pezzo di cui sto parlando in particolare è:

  • Il nome file
  • Il nome dell'azienda
  • L'autore e la data di creazione
  • Informazioni sul copyright

Sono piuttosto dubbioso sul fatto che tutte le informazioni siano disponibili in git, ad eccezione delle informazioni sul copyright.

Preferirei che fosse tagliato tutto.

//
//  Copyright © 2017 SomeCompany. All rights reserved.
//

/// A queue is a list where you can only insert new items at the back and remove items from the front. 
/// This ensures that the first item you enqueue is also the first item you dequeue. 
/// First come, first serve!
struct Queue<T> {
    ...
} 

I colleghi di lavoro pensano che io sia irrazionale poiché ritengono che l'autore originale sia utile per sapere chi ha originariamente creato il file e quando lo hanno creato, ma il mio argomento è che diventa obsoleto non appena qualcuno lo modifica (in più, tutte le informazioni sono disponibili in vcs comunque)

Voglio sapere se sembra ragionevole eliminare le informazioni su nome file, azienda e autore.

    
posta Oliver Atkinson 30.08.2017 - 11:12
fonte

1 risposta

3

C'era una volta prima del versioning dei file, mantenendo le informazioni di intestazione di base come ciò che fa la classe, quando è stata creata, e da chi era in qualche modo necessario. Se qualcosa non funzionava, dovevi essere in grado di contattare il programmatore che l'ha realizzato se, per nessun altro motivo, di dargli un completo riassunto.

Al giorno d'oggi, il controllo delle versioni dei file ha eliminato la maggior parte di queste informazioni, ma le vecchie abitudini sono dure a morire. Potrebbe anche essere utile fornire un breve riassunto di ciò che la classe o il file definisce / definisce, dato che nessuno ti ucciderà durante il sonno per aver scritto eccessivo commenti, anche se potresti ricevere alcuni sguardi d'occhio .

I miei pensieri sono che se le intestazioni sono presenti durante un progetto, è meglio essere coerenti, anche se pensi che sia sciocco e non necessario. Altrimenti, concentrati sul rendere il codice chiaro e conciso piuttosto che riempire le righe tra i commenti. Solo se il codice non è chiaro (possono gli dei di programmazione salvarci tutti) dovresti scrivere alcune righe spiegandole al meglio delle tue capacità.

    
risposta data 30.08.2017 - 12:32
fonte

Leggi altre domande sui tag