Sto estraendo interfacce da alcune classi in .NET e non sono completamente sicuro sul livello di dettaglio della descrizione da utilizzare per alcuni membri dell'interfaccia (proprietà, metodi).
Un esempio:
interface ISomeInterface
{
/// <summary>
/// Checks if the object is checked out.
/// </summary>
/// <returns>
/// Returns true if the object is checked out, or if the object locking is not enabled,
/// otherwise returns false.
/// </returns>
bool IsObjectCheckedOut();
}
class SomeImplementation : ISomeInterface
{
public bool IsObjectCheckedOut()
{
// An implementation of the method that returns true if the object is checked out,
// or if the object locking is not enabled
}
}
La parte in questione è la sezione <returns>...</returns> della descrizione di IsObjectCheckedOut nell'interfaccia.
Va bene includere un tale dettaglio sul valore di ritorno nell'interfaccia stessa, poiché il codice che funzionerà con l'interfaccia dovrebbe sapere esattamente cosa farà quel metodo? Tutte le attuali implementazioni del metodo faranno proprio questo. Ma va bene limitare le possibili altre implementazioni future / dalla descrizione in questo modo?
O questo non dovrebbe essere incluso nella descrizione dell'interfaccia, in quanto non vi è alcun modo per assicurarsi che le implementazioni future / future facciano esattamente questo? È meglio essere il più generale possibile riguardo all'interfaccia in tali circostanze?
Attualmente sono propenso a quest'ultima opzione.