O que eu mais utilizo é o método de extração, sempre transformando o código em métodos menores. Ajuda bastante na leitura desde que você dê bons nomes e use os parâmetros de forma consciente nos métodos, além de também contribuir para que não haja grandes blocos de indentações.
Também concordo com opinião do Tio Bob em relação aos comentários, mas gosto de deixar os métodos públicos das classes sempre documentados.
O método da extração é lindo cara, realmente muda vidas. Tenho aplicado um processo de refatoração em alguns componentes e diminuir as responsabilidades de cada um deles está ajudando muito na reusabilidade e na manutenabilidade. Altamente recomendado!
Sobre os comentários, você está errado. Remova todos eles. 😡🤣 Brincadeira, óbvio. Sim...alguns comentários são necessários e a forma que está utilizando eles faz todo sentido. Mas eu consideraria (não sei se foi o que quis dizer, se eu estiver enganado, desculpe) deixar não em comentários no código. Mas criar uma wiki, por exemplo e agregá-los lá. Obrigado por ter comentado!
Como seria essa wiki, tens exemplos?
A forma que eu faço é esta: https://imgur.com/a/klcZsjt
O IOSNumericFieldDoneWidget, pode não estar sendo visto, mas só de por o mouse e ter acesso a essa breve documentação, já podemos ter uma noção de seu comportamento.
Infelizmente não tenho em mãos nenhum exemplo público. Mas não é difícil explicar! É bem similar a um readme.md, porém o foco é direcionado. Num readme você aborda tudo. Os contribuidores, tecnologias, clientes...já a wiki foca em questões e/ou títulos objetivos:
Uma boa WiKi pode se tornar um guia não apenas para os atuais desenvolvedores, mas para futuras agregações no time de desenvolvimento. É praticamente um tabnews internalizado 🤓.
E claro, de acordo com os relacionamentos dos conteúdos da wiki, é possível criar wikis direcionadas, que foquem apenas em Banco de Dados, Front e Back...e por aí vai, mas claro, precisa ter controle. De nada adianta encher lá de conteúdo "fútil" como por exemplo:
É muito possível que existam outros formatos. Mas hoje é este que usamos e funciona bem. Isso não exime documentações, ok? Nada anula a necessidade de uma boa documentação. Mas pesquisar num conteúdo direcionado, objetivo e personalizado (porque não são regras gerais, mas sim regras próprias para cada projeto e muitas vezes, regras de negócio). E você pode hospedar onde preferir...um documento compartilhado no OneDrive ou internamente numa cloud como Azure ou AWS.