Il seguente commento è chiaro: "Fino a contestato" [chiuso]

Naviga le tue risposte
4

Supponiamo di vedere il seguente modello nel codice: 

function foo() {
    ...
    var someFlag = false; // Until contested
    for/while/if () {
        ...
        // Possibly deeply nested in some non-trivial logic
        someFlag = true;
        ...
    }
    if (someFlag) {
        // Additional processing of some sort
    }
    ...
}

Senza ulteriori descrizioni, hai una buona idea di cosa sta tentando di descrivere questo commento "until contested"? Pensi che sarebbe un commento utile per capire il codice che stavi leggendo?

It's describing a boolean flag which starts off as being set to one value, until some later point(s) when it may switch to the other value but, not back once it has been set. Common uses: "found" / "completed" / "did change something" etc...

Hai qualche modo in cui preferisci descrivere detto schema di codice? "Fino a contestato" è il modo più conciso / chiaro che ho trovato per taggarlo rapidamente nel mio codice per facilità di lettura nei casi che non giustificano un commento più dettagliato. Mi chiedo se sarebbe un commento ragionevole da usare nel codice che scrivo anche in una squadra professionalmente.

    
posta Mark 10.03.2017 - 20:13
fonte

3 risposte

2

Un concorso coinvolge due o più parti che potrebbero essere in conflitto (notare la radice latina comune contestari ). Se dovessi vedere questo commento, potrei presumere che ci sia una sorta di conflitto di thread in effetti, o che c'è qualcosa di incerto sulla condizione anche se il flag è impostato su true .

Suggerirei quanto segue:

  1. Il commento non dovrebbe essere necessario se la variabile è denominata correttamente. Dopo tutto, il commento appare solo una volta mentre la variabile sarà dappertutto, apparentemente. Hai intenzione di commentare ogni riferimento ad esso?

  2. La variabile dovrebbe essere nominata in un modo che descriva cosa sta facendo. Vorrei offrire un suggerimento, ma la tua domanda è troppo generica. Non esiste un nome generico che funzioni in tutti i casi; inoltre, eviterei di pensare a un nome generico . A volte le cose dovrebbero essere specifiche e non generali.

  3. Se insisti su un nome generico, flag è adeguato ed è certamente generale.

risposta data 10.03.2017 - 20:37
fonte
1

Il commento non è utile. Sono uno che preferisce molti più commenti di molti su questo sito che preferiscono il codice per essere autoesplicativo senza commenti.

In questo caso la variabile flag ha bisogno di un buon nome descrittivo. Nessun commento necessario. Nessun commento salverebbe la situazione in cui il nome della variabile è cattivo.

Il codice sarebbe quindi autoesplicativo.

    
risposta data 10.03.2017 - 20:37
fonte
0

Commenti il cui unico scopo è descrivere esplicitamente come funziona il codice non sono utili a qualcuno che legge il codice perché il codice stesso fornisce le stesse informazioni - è effettivamente una forma di duplicazione.

L'unica eccezione a questa situazione potrebbe essere per qualcosa di naturalmente difficile da comprendere come un algoritmo scientifico estremamente complesso - nel qual caso un commento probabilmente deve dire qualcosa come "Questo è l'algoritmo di foo" in modo che il lettore possa andare a leggere il requisito appropriato o prenotare per comprenderlo.

Per evitare la necessità di commenti che spieghino la logica del codice, considerare attentamente i nomi delle variabili e delle funzioni; considera anche la lunghezza e la complessità ciclomatica delle tue funzioni, forse il tuo codice trarrebbe vantaggio dalla suddivisione in pezzi più piccoli.

Assumendo codice pulito / modulare / leggibile, come lettore o manutentore le informazioni che sono più preziose sono di solito sui tipi di decisioni e compromessi fatti dall'autore, e le informazioni che l'autore aveva in testa nel momento in cui non può essere espresso in codice semplicemente attraverso la denominazione.

Alcuni esempi forzati:

  • "Quando è vero, indica che il sistema è in attesa di autorizzazione e impedisce all'utente di annullare"

  • "Questo flag viene pubblicato sul servizio di gestione del sistema ogni 30 secondi, se il gestore di sistema non riceve l'aggiornamento o riceve uno stato errato, quindi la sincronizzazione fallirà".

  • "Questo edge-case si verifica solo quando l'utente è stato de-autorizzato dal server da un amministratore ma la sua app client non risponde al messaggio costringendoli a disconnettersi."

  • "L'API FooBar di ACME è limitata a 10 chiamate API ogni 5 secondi, quindi una volta raggiunto il conteggio, il thread deve dormire per 5 secondi per evitare la limitazione".

In breve, considera il modo in cui qualcuno in futuro (magari anche te stesso in futuro) potrebbe accidentalmente e ingenuamente "fare la cosa sbagliata" al tuo codice e finire per romperlo o finire per creare qualche parte involontaria -effetti perché non avevano la stessa profondità di comprensione o la visione di 'immagine più grande' come hai fatto quando l'hai scritta.

    
risposta data 10.03.2017 - 21:01
fonte

Leggi altre domande sui tag

Designing Consistent Module di fatturazione In che modo le soluzioni e i progetti di Visual Studio devono essere associati ai progetti GIT e ai repository di Visual Studio Online?