Ho lavorato a un progetto ASP.NET Web Api 2 come esercizio di apprendimento e mi chiedevo quale fosse la norma riguardante i commenti.
Uso il modello di repository / servizio, e tutto è molto disaccoppiato, il che si traduce nell'avere un gran numero di classi il cui scopo è abbastanza chiaro. Do anche un nome alle mie variabili in un modo che si spiegano da sole.
Questo mi fa pensare a cosa dovrei effettivamente commentare in questo scenario.
- Dovrei limitarmi ai riassunti delle classi (anche se la classe stessa è auto-esplicativa)?
- Per quanto riguarda i metodi auto-esplicativi?
- Le classi di dati / entità aziendali richiedono un riepilogo?
- E riguardo le interfacce?
Per dare un po 'più di contesto, ecco una delle mie classi di repository che fornisce funzionalità CRUD:
public class UserRepository : RepositoryBase<User, decimal>
{
private readonly ShortStuffContext _context;
public UserRepository(ShortStuffContext context)
{
_context = context;
}
public override IEnumerable<User> GetAll()
{
return _context.Users.BuildUser();
}
public override User GetById(decimal id)
{
return _context.Users.FirstOrDefault(u => u.Id == id).BuildUser();
}
public override CreateStatus<decimal> Create(User entity)
{
if (_context.Users.Any(u => u.Id == entity.Id))
{
return new CreateStatus<decimal> { status = CreateStatusEnum.Conflict };
}
var user = new Data.Entities.User();
user.InjectFrom<SmartConventionInjection>(entity);
_context.Users.Add(user);
_context.SaveChanges();
return new CreateStatus<decimal> { status = CreateStatusEnum.Created, Id = user.Id };
}
public override UpdateStatus Update(User entity)
{
var dbUser = _context.Users.FirstOrDefault(u => u.Id == entity.Id)
.InjectFrom<NotNullInjection>(entity);
if (dbUser != null)
{
var changeTrackerUser = _context.ChangeTracker.Entries<Data.Entities.User>()
.FirstOrDefault(u => u.Entity.Id == entity.Id);
changeTrackerUser.CurrentValues.SetValues(dbUser);
if (_context.SaveChanges() == 0)
{
return UpdateStatus.NoChange;
}
return UpdateStatus.Updated;
}
return UpdateStatus.NotFound;
}
public override void Delete(decimal id)
{
var user = _context.Users.FirstOrDefault(u => u.Id == id);
_context.Users.Remove(user);
_context.SaveChanges();
}
}
Quindi, in una classe come questa, vale la pena inserire un riassunto come "Fornisce funzionalità CRUD per l'Entità dati utente" (e poi ripetere quel sommario per ogni altro repository) o no? Che dire dei commenti sui metodi o dei commenti in linea?
Modifica: il mio progetto è su Github . So di aggiungere commenti a metodi più complessi e sto pianificando di aggiungere presto commenti alle estensioni e alle classi ValueInjecter (che contengono di gran lunga il codice più complesso). Oltre a ciò, qualsiasi consiglio su dove inserire commenti è molto gradito.