Tengo un colega que insiste en que su código no necesita comentarios, es "auto-documentación".

He revisado su código y, si bien es más claro que el código que he visto producir a otros, aún no estoy de acuerdo con que el código de auto-documentación sea tan completo y útil como el código comentado y documentado.

Ayúdame a entendersu punto de vista.

¿Qué es el código auto documentado?¿Puede realmente reemplazar código bien comentado y documentado?¿Hay situaciones donde es mejor que el código bien documentado y comentado?¿Hay ejemplos en los que el código no pueda autodocumentarse sin comentarios?

Tal vez sean solo mis propias limitaciones, pero no veo que pueda ser una buena práctica.

Esto no pretende ser un argumento; por favor, no mencione las razones por las que un código bien comentado y documentado es de alta prioridad. Existen muchos recursos que lo demuestran, pero no son convincentes para mi compañero. Creo que necesito entender más completamente su perspectiva para convencerlo de lo contrario. Comience una nueva pregunta si es necesario, pero no discuta aquí.

Wow, respuesta rápida! Lea todas las respuestas existentes y proporcione comentarios a las respuestas en lugar de agregar nuevas respuestas, a menos que su respuesta sea realmente diferente a cualquier otra respuesta aquí.

Además, aquellos de ustedes que están discutiendo contra el código de auto-documentación, esto es principalmente para ayudarme a entender la perspectiva (es decir, los aspectos positivos) de los evangelistas del código de auto-documentación. Espero que los demás te rechacen si no te mantienes en el tema.