Como posso pedir ao meu chefe (de maneira educada) para comentar o código dele?


72

Estou sendo ensinado pelo meu chefe (eu terminei a escola e ele queria alguém com um pouco de experiência em programação, então ele me escolheu para me treinar no que a empresa é especializada) e começou a trabalhar com aplicativos ASP.NET MVC , alguns HTML e CSS . Eu estou bem com o material de web design que ele me fornece (é bem simples de entender sem esclarecimentos).

Mas, por exemplo, ele me dá uma tarefa relacionada ao ASP.NET MVC, ele explica muito bem. Mas ele não explica nada no código que acabou de me dar. (Usamos o controle de origem no Visual Studio 2013 ), portanto, são literalmente centenas de linhas de código, sem nenhum conhecimento sobre o que ele deve fazer. O tipo de código que estou vendo é um código que nunca vi antes, por isso é realmente difícil tentar descobrir.

Eu tentava fazer mais perguntas, mas ele está sempre trabalhando (é o seu próprio negócio), e sinto que ele pode ficar irritado com todas essas perguntas que tenho em minhas mãos.

Então, apenas algo que vai me ajudar até eu entender as coisas, como posso pedir ao meu chefe para colocar comentários em seu código que ele me dá, mas educadamente?


2
Comentários não são para discussão prolongada; esta conversa foi movida para o bate-papo .
Maple_shaft

11
Uma alternativa para perguntar é usar ferramentas de indexação e navegação de código fonte, como o SourceGraph .
Dan Dascalescu

Recentemente, comecei em uma equipe trabalhando em um aplicativo MVC5 grande (> 100k linhas). Há 150 testes de unidade para a coisa toda e todos eles foram adicionados por mim nos últimos meses. Os poucos comentários no código são principalmente em outros idiomas. Welcome to business programming :)
Mark K Cowan

Perguntas como "Como peço ao X que faça Y" geralmente são melhores no Workplace quando X envolve um colega.
Blrfl

Respostas:


130

Você está no "fundo do poço" e, na minha opinião, essa é a melhor maneira de aprender. Não porque você está olhando para coisas que você não tem idéia, mas porque isso o força a ter mais recursos e a descobrir quais componentes desempenham qual papel em um sistema no qual você é novo.

Não ajuda que seu chefe esteja ocupado demais para lidar com alguém que é curioso (e você está totalmente dentro do seu direito de ser curioso; você deseja aprender, o que é bom). Infelizmente, porém, pedir ao seu sénior que mude seu estilo e abordagem em prol do seu aprendizado pode não ser muito bom, especialmente porque você está lidando com alguém que diz estar ocupado.

Estar sentado na frente de milhares de linhas de código com as quais você não está familiarizado é a norma. Você nem sempre pode explicá-lo em preto e branco com comentários. No entanto, para o aprendizado enquanto você é novo, se você sentir que definitivamente precisa pedir comentários, talvez explique o porquê. Explique que é porque você não quer incomodá-lo com perguntas, pois ele costuma estar ocupado. Isso não apenas parecerá muito menos como você está dizendo para ele fazer alguma coisa, mas também abre a discussão para discussões sobre como ele pode preferir deixar de lado as perguntas.


185
+1 para "Estar sentado na frente de milhares de linhas de código com as quais você não está familiarizado é a norma" - isso nunca aparece nos cursos de programação e sempre aparece no trabalho.
Pjc50

11
Obrigado por me dar esperança, eu estava pensando em simplesmente deixar o emprego e ir para a universidade ou algo assim. Falei com ele há pouco tempo e ele disse que está muito impressionado com o meu progresso blah blah haha ​​.. @ pjc50 Eu concordo totalmente com você em basicamente fazer o teste e a lição depois. Provavelmente não aprendi mais no último mês do que os três anos que tive na escola!
Aidan Quinn

9
Exatamente. Programar como comércio requer efetivamente um aprendizado (possivelmente autodidata), enquanto os cursos de CS podem conter muito pouca programação real. Eles são simbióticos, mas não são a mesma coisa. Você não precisa ir à universidade para ser um ótimo programador, mas facilita muito a contratação, mesmo que o curso tenha pouca relevância para o trabalho que você está se candidatando.
Pjc50

11
@AidanQuinn, Síndrome do Impostor ( pt.wikipedia.org/wiki/Impostor_syndrome ) pode ser muito forte no início de um novo emprego e ainda mais no início do seu primeiro. Se ele disser que você está indo bem, aceite a palavra dele.
Celos

6
A programação é, na maioria das vezes, incompetente com breves explosões de sentimentos de absoluto gênio divino.
MrDosu

75

Primeiro, rastrear milhares de linhas de código desconhecido e sentir-se perdido é como todo projeto de software está, em todo lugar, desde o início dos tempos.

A maior diferença entre você e um programador experiente é que você não está acostumado a isso.


Alguns pontos a serem lembrados:

  1. Com esforço suficiente, todo pedaço de código é compreensível. Muitas pessoas se sentem frustradas se não conseguirem descobrir algo dentro de alguns minutos. Seja mais paciente que isso.

  2. Um bom chefe é o mais aberto possível a interrupções e perguntas. Um bom funcionário tenta o máximo possível para minimizar interrupções e perguntas. Esteja consciente disso.

  3. Interrupções são mais caras que perguntas. Você pode fazer melhor uso do seu tempo e do tempo do seu chefe consolidando suas discussões e nunca terminando uma conversa se sentindo confuso.

  4. Seu chefe é um programador melhor que você. (Provavelmente.) Isso não quer dizer que você não possa ser mais forte em algumas áreas, mas no geral a experiência dele é maior. Até você ter muita experiência, certifique-se de aprender com a experiência dele o máximo que puder.

  5. Se você tiver certeza de que mais comentários ajudariam significativamente o código, pergunte ao seu chefe. "É difícil para mim entender o que está acontecendo em alguns lugares. Quando eu entendo as coisas, você se importa se eu adicionar comentários?" Talvez ele odeie comentários. Talvez ele ame isso. Talvez ele seja indiferente.

No final, no entanto, é possível que daqui a alguns meses você se lembre de perguntar isso e pense: "Huh, eu me pergunto com o que eu tive um problema? Isso não é tão ruim. Hum, bem, não importa".


6
Eu gosto especialmente do ponto 3. Às vezes, é benéfico escrever um e-mail rápido de duas linhas pedindo que ele lhe ajude, mesmo que ele esteja sentado no escritório a alguns metros de você. Isso permite que ele determine quando ele está pronto para ser interrompido e permite que você tenha mais tempo para criar uma lista mais completa de perguntas antes que a discussão realmente ocorra.
Phil

11
idem para @Phil. Você ficará surpreso com quantas perguntas você descobrirá a resposta sozinho, elaborando cuidadosamente uma pergunta clara por email. Apenas o processo de explicar sua confusão com precisão pode acender as luzes. Não posso dizer quantas vezes escrevi e-mails desse tipo que nunca foram enviados porque descobri.
kmote 12/02

3
@kmote, tenho muitas perguntas não formuladas Stack Overflow que aconteceram da mesma maneira :)
Paul Draper

18

Se seu chefe não tem tempo para responder a todas as suas perguntas, por que você acha que ele terá tempo para comentar seu código legado? Além disso, o que faz você pensar que os comentários dele realmente descreveriam os trechos que você não entende por enquanto? Para minha experiência, tentar mudar o estilo de programação de seus chefes, apenas perguntando a ele, não funcionará, educado ou não.

A melhor coisa que você pode fazer em tal situação: comente as partes do código que você precisa entender para fazer seu trabalho sozinho - depois de entender essas partes, é claro, e depois de obter um compromisso do seu chefe, tudo ficará bem. Se você ou seu chefe temem que você possa quebrar algo adicionando comentários, adicione-os em um ramo separado e pergunte ao seu chefe se ele reservará algum tempo para revisar seus comentários antes que eles sejam mesclados ao tronco. Como seu chefe tem apenas um orçamento de tempo restrito, tente descobrir o que uma determinada parte faz primeiro investindo uma quantidade razoável de tempo. Se você realmente ficar preso, escreva sua pergunta em uma lista e pergunte ao seu chefe, por exemplo, uma vez por dia, em vez de incomodá-lo por 30 minutos. De acordo com a minha experiência, essa abordagem funciona com a maioria das pessoas, mesmo que estejam muito ocupadas, desde que estejam dispostas a ajudá-lo - o que certamente é o caso da sua situação.

Dessa forma, você tem certeza de obter os comentários necessários e seu chefe verá onde você precisa de informações adicionais e se você acertou. E desde que você se restrinja a comentar apenas as coisas não óbvias, há uma boa chance de seus comentários aumentarem a qualidade geral da base de código, o que pode não apenas trazer benefícios não apenas para você, mas também para todos os outros que tem que lidar com o código, incluindo seu chefe.


3
Você também pode propor um patch adicionando alguns comentários ao seu chefe.
Basile Starynkevitch

2
@BasileStarynkevitch: é claro, para evitar o risco de quebrar algo, ele pode adicionar os comentários em um ramo separado primeiro e pedir ao seu chefe para revisar os comentários antes que eles sejam mesclados ao tronco.
Doc Brown

2
@DocBrown Trabalhar em uma ramificação separada é uma boa estratégia em geral, mas se adicionar comentários interrompe alguma coisa, eu diria que a base de código tem problemas maiores ......
a CVn

11
@ MichaelKjörling: na verdade, isso é algo que o OP deve discutir com seu chefe. O uso de uma ramificação diferente tem duas vantagens: evita quebras acidentais cometendo erros de digitação, como excluir uma linha demais ao excluir um comentário obsoleto, e pressiona o chefe a revisar os comentários.
Doc Brown

@ MichaelKjörling não se trata de comentários quebrando algo, mas os comentários precisam corresponder ao código real.
Hugo Zink

8

Em primeiro lugar, deixe que este seja um exemplo para você comentar seu código corretamente, gafanhoto!

Então, eu tenho que fazer isso o tempo todo. Eu tenho minha cópia local em check-out, e eu a revisto e comento. (Posso retirar todos eles de novo se quiser fazer o check-in novamente - ou deixá-los dentro, se ninguém se importar.) Então, quando realmente não consigo ver mais, posso perguntar a alguém, aqui, acho que sim isso (o que eu comentei), estou certo? Então você pode ter feito os comentários reais, mas está feito e esse é o ponto.


5

Isso é mais do que apenas um pedido pessoal. Você está tentando mudar hábitos / cultura, e isso não é fácil. Certamente não é algo que pode ser realizado por uma conversa no corredor ou por um email. Vai levar algum esforço de sua parte.

Seja a mudança que você deseja ver no mundo.

A citação pode ser atribuída falsamente a Mahatma Gandhi, mas é um conselho aplicável. Ao tentar decifrar a base de código, escreva os comentários que você gostaria de ver, da melhor maneira possível, e os comprometa, depois de serem analisados ​​pelo seu chefe. Vantagens:

  • Você está sendo proativo, em vez de irritante.
  • Você está dando um bom exemplo. Na melhor das hipóteses, seu chefe / equipe verá os benefícios e seguirá o exemplo.
  • Alguns dos comentários provavelmente dirão /* Mystery parameter 3 */ou /* 2015-02-09 AidanQuinn: Is this code ever called? */- essas são oportunidades para seus colegas documentarem o código corretamente ou corrigirem erros latentes.
  • Se, durante a revisão pré-confirmação, for descoberto que um comentário que você escreveu é impreciso, seus colegas agora sabem que o código não estava claro.

Evite reescrever ou refatorar ao fazer isso, e a introdução de comentários deve ser quase livre de riscos. Se você reescrever alguma coisa, mantenha essas alterações como confirmações separadas.

(Antes de embarcar nesse projeto, no entanto, certifique-se de que suas expectativas para comentários sejam razoáveis. Se sua idéia de código bem comentado está fora da norma ( Exemplo 1 , Exemplo 2 ), então você só estará enganando você mesmo.)


5

Eu não pediria comentários adicionais, mas aqui estão algumas idéias para você:

  1. Agende uma sessão com seu chefe e faça com que ele repasse o código em alto nível. Isso deve ajudá-lo a começar. Eu esperaria algumas horas, talvez meio dia, para que você possa se atualizar. Isso deve incluir design geral, padrões usados ​​etc.
  2. Crie um projeto de testes e comece a escrever testes de unidade no código, isso ajudará você a entendê-lo sem impactá-lo. Você também pode encontrar alguns bugs!
  3. Depure o código conforme necessário para entender determinadas áreas.
  4. Tire um aprimoramento ou bug do backlog e trabalhe nele.

Os comentários são bons, mas se o código for escrito de maneira direta, deverá ser compreensível após alguns dias.

Além disso, não espere entender tudo, é melhor focar em áreas-chave primeiro e depois expandir o conhecimento da base de código conforme necessário.


2

Eu estive em uma situação muito semelhante à sua há cerca de um ano atrás. Comecei a trabalhar com pouca experiência em programação (embora soubesse um pouco de OO e algumas outras linguagens para começar) e a única pessoa que estava me ensinando tinha muito pouco tempo. Ele sempre foi útil, mas eu senti que não gostaria de fazer todas as perguntas que fiz.

Outros já sugeriram coisas extremamente úteis aqui (escrever testes de unidade, por exemplo, mas da minha própria experiência, isso é algo que teria ido um pouco "longe demais" para mim do zero; ou comentar você mesmo partes do código, mas isso pode ser difícil dependendo do primeiro ponto / pergunta que vou fazer em um minuto). Os pontos a seguir resumem o que fiz e o que me ajudou, mas depende muito de onde exatamente estão seus problemas.

Além disso, eu tenho que concordar com @AK_, que disse que você realmente não precisa de comentários em C #. Isso pode não estar 100% correto (acho que há áreas em que os comentários definitivamente ajudam, por exemplo, código pesado para reflexão), mas, em essência, é. Se você escrever realmente 'código limpo' com métodos e variáveis ​​bem nomeados e tiver muitas 'pequenas partes' de código, elas serão quase totalmente desnecessárias. Toda vez que senti a necessidade de comentários ao ler código até agora, depois de entender o que fazia, fiquei muito infeliz com a maneira como foi feito e pensei que poderia ter sido muito mais claro em primeiro lugar por uma boa refatoração. Edit: Eu estou falando especificamente sobre comentários C # aqui, não documentação (seja documentação separada ou comentários XML), pois acho que a documentação é sempre importante.

  • Identifique quais são exatamente os seus problemas e se você pode categorizá-los. Ou seja, você ainda tem problemas com o próprio idioma ou não entende uma sintaxe específica (por exemplo, expressões lambda e LINQ em geral, ou Reflexão)? Se você não entender as linhas de código, não entenderá o que todo o método / bloco faz; portanto, comentar você mesmo será difícil. Em vez disso, pegue um bom livro ('C # em poucas palavras' era para mim, mas ouvi dizer que 'C # em profundidade' também é espetacular) e leia as coisas que encontrar. A categorização antecipada desses problemas facilita isso, pois você pode preencher 'lacunas maiores' de uma só vez ou até perguntar ao seu chefe sobre isso, pois não são mais muitas perguntas, mas sim explicar um único assunto ou as construções mais usadas para que você pode obter um enorme 'impulso'

  • Paralelamente ao exposto, tentei me familiarizar com a 'codificação limpa' e as melhores práticas gerais (não específicas do idioma). O efeito disso pode não ser imediato, mas será recompensado mais cedo ou mais tarde, quando você precisar estender o material existente ou se perguntar por que alguém criou tantos métodos pequenos em vez de um onde tudo está contido ;-)

  • Conheça os padrões de design comuns. Eles podem estar aparecendo aqui e ali no código que você está lendo, e se você os reconhecer, isso imediatamente lhe dará um momento do a-ha. Mesmo que você entenda o que o código que você vê lá faz, você pode se perguntar por que isso é feito dessa maneira, e descobrir isso sozinho geralmente não é tão fácil.

Por favor, não tome o texto acima, enquanto eu faço suposições sobre sua 'habilidade', muitas vezes alterno acidentalmente entre falar sobre minhas experiências e falar 'com você'. É principalmente o que encontrei e o que fiz . Como já foi dito, essa pode ser uma experiência muito boa e é praticamente o padrão no trabalho ler código que não é seu e que você não conhece muito antes. Mas pode ser realmente gratificante finalmente entender o que está acontecendo lá e reconhecer-se melhorando com essa 'habilidade' específica. Aproveite isso como uma oportunidade para aprender muito em muito pouco tempo, boa sorte! :)


1

Você provavelmente não vai fazê-lo mudar de estilo.

O que você pode fazer é fazer muitas perguntas e anotar as respostas.

Eu herdei uma enorme base de código no meu último trabalho, pouca documentação e poucos comentários. Então, eu tentava por meia hora o mesmo problema; se ainda não conseguisse descobrir, perguntaria a alguém que o escreveu ou soube usá-lo. Então eu documentaria todas as coisas que ele me disse. A maioria foi encontrada em nossa documentação, alguns foram inseridos no código como comentários. Depois de um ano lá, eu praticamente escrevi uma grande parte da nossa documentação e sabia muito sobre a base de código.

Boa sorte!


1

Eu estava tendo o mesmo problema. Sou estudante de phyzist e tenho boa experiência em programação. Eu estava programando em várias línguas, mas nada para aplicação premium.

Candidatei-me a um emprego para desenvolvedor web e eles instantaneamente me colocaram no back-end da programação na web. Quando o chefe me mostrou a API básica para a aplicação REST do nó, eu estava pensando que eu jogaria fora. Eu nunca vi funções com retorno de chamada e sintaxe tão estranha. E pergunto ao meu chefe se tenho um problema. Se não entendo nada do código. Ele está triste, não, ele está triste por eu ter 1 mês para descobrir e, nesse meio tempo, farei um CMS para me testar com outro frontend.

Bem, e eu fui uma linha de código no momento e google tudo o que eu não sei. Então, uma semana se passou e eu estava familiarizado com o código o suficiente para poder colaborar com o front ender. Meu código no começo era uma porcaria, mas me me três meses depois disso! Estou codificando melhor e mais rápido que o nosso arquiteto de software!

Sugiro que você nunca pare de aprender! Minha moto -> Continue aprendendo e mantenha a calma :) Não dependa do chefe, seja independente e pergunte diretamente, mas apenas os problemas mais difíceis. Porque você será feliz depois de descobrir isso por sua própria pesquisa. E lembre-se, quando você parar de aprender algo errado, aprenda todos os dias como ser um bom programador.

Se você aprender com o chefe, nunca será melhor do que ele: estabeleça seu próprio padrão, aprenda digitação cega, plug-in VIM ou VIM para seu IDE, Linux wmii, para que um dia você vá além do chefe e seja melhor que ele!


é difícil ler este post (parede de texto). Você se importaria de editá -lo em uma forma melhor?
Gnat

Desculpem a minha ignorância :)

pós atualizado é muito mais fácil de entender, mas o que eu posso ver agora parece apenas repetir pontos já feitas (e visivelmente melhor explicadas) em respostas anteriores, especialmente em (boa editar!) esta
mosquito

11
Me desculpe, eu estou fazendo isso de manhã antes do trabalho e não tenho muito tempo em minhas mãos, o objetivo é que o proprietário da pergunta veja, pelos pontos que eu não me importo :)

0

Como engenheiro de software há 20 anos, trabalhando principalmente em assuntos relacionados à segurança (SF-PD), eu diria que seu chefe pode não ser a pessoa que você quer ser seu exemplo. A falta de comentários é um sinal de um programador amador autodidata que nunca aprendeu a fazer o trabalho corretamente ou de um engenheiro inexperiente. Ou talvez um engenheiro que simplesmente não tenha tempo - prazos e conveniência podem fazer coisas horríveis ao seu código! ;) É definitivamente um anti-padrão para todo engenheiro de software competente.

Seu chefe pode ser um codificador muito bom, mas parece que ele não é um bom engenheiro de software. Um engenheiro usa a experiência coletiva do grupo para evitar as armadilhas pelas quais outras pessoas já foram capturadas. Os comentários eficazes fazem parte da experiência coletiva do grupo em software, da mesma forma que a análise de tensão faz parte da experiência coletiva do grupo em engenharia mecânica. O que conta como um comentário eficaz é mais fluido e é definitivamente algo que você obtém da experiência.

O mais básico é que os comentários não devem dizer o que uma linha de código faz. Há momentos em que os comentários para dizer o que uma função faz também são supérfluos (especialmente em C #). Comentar demais pode ser tão ineficaz (e um indicador da falta de experiência) porque você não consegue encontrar as coisas importantes na escória. Como iniciante, você ainda pode estar trabalhando para descobrir o "quê" do código e, para isso, você só precisa ler e entender o que ele fez.

O importante para os comentários é que eles dizem POR QUE uma linha de código ou função faz o que faz, onde isso pode não ser óbvio. Você precisa configurar o módulo X antes do módulo Y? É importante verificar um código de retorno para ver se um arquivo já estava aberto ou estamos ignorando conscientemente o código de retorno porque ele foi verificado em outro lugar? O "porquê" do código será relevante para todos, independentemente da experiência - e será relevante para ele em seis meses, quando ele se esquecer do bom motivo para fazer algo de uma maneira específica. Comentar não é apenas para outras pessoas, é para ajudá-lo no futuro também.

Se você quiser evitar irritar seu chefe, faça perguntas inteligentes. Concentre-se em perguntar sobre o "porquê" e tente descobrir o que é você mesmo (a menos que seja genuinamente obscuro). Nenhum bom chefe se importará de fazer perguntas se elas não forem o tipo de coisa que você poderia encontrar no R-ing TFM. E nenhum bom engenheiro se importará de ser solicitado a fazer algo que torne a vida de outro engenheiro significativamente mais fácil, com pouco custo para eles. (Apenas não peça a ele para preencher os comentários em toda a base de código!;)


11
O primeiro parágrafo implica que o chefe - e a maioria de nós - é incompetente porque ele (supõe-se) não comenta da maneira que deveria. Isso é lamentável, porque o restante dos conselhos sobre quando e como comentar é realmente razoável. Muitos de nós provavelmente concordariam com isso se não fôssemos tão desanimados no começo.
John M Gant

Os últimos três parágrafos da sua resposta são bastante úteis, @Graham. Por favor, não deixe que alguns votos negativos o desanimam.
DavidS

Fiquei surpreso ao ver os votos negativos. As informações sobre o que, como e por que comentar estão inexistentes. Concordo com os outros que sua especulação sobre a competência do chefe dele é improdutiva.

@ Superstringcheese: Infelizmente, muitas vezes você recebe votos negativos por manter uma posição diferente de "Torta de mamãe e maçã". Não concordo com parte do que você disse (não no primeiro parágrafo! É totalmente válido na IMO) - mas você ainda recebe um voto positivo por princípio.
einpoklum - restabelece Monica

0

Estive em uma situação semelhante, eu diria

  1. Seu chefe pode querer que você aprenda o caminho sujo (percorrendo o código que você não tem idéia) por um motivo. É assim que aprendemos mais em um mês no trabalho que em um ano na faculdade, como mencionado em outras respostas.

  2. Esta é "a norma", como mencionado em outras respostas. Você deve estar mais preocupado com por onde começar, como abordar e com o que focar do que tentar entender todas as linhas de código imediatamente. Pergunte ao seu chefe sobre as ferramentas certas e maneiras de depurar / percorrer o código. Esse tipo de pergunta comprará alguns pontos.

  3. Em uma base regular, continue abordando seu chefe para obter feedback sobre como está se saindo, para ter uma ideia de como está em termos percentuais, supondo que seu chefe tenha visto um bom número de pessoas na mesma situação e tenha uma ideia de como eles foram.

  4. Aproveite isso como uma oportunidade e, à medida que melhorar o entendimento do código, continue adicionando comentários que você originalmente esperava perguntar ao seu chefe.


0

Se você realmente quiser pedir a ele para colocar comentários em seu código (eu não o recomendo), sugiro encontrar um código que você precisa editar que possa realmente usar alguns comentários (a maioria é auto-explicativa) e fazer a pergunta sobre assim "Eu estava olhando para este código aqui e estou tentando descobrir [problema que você está tendo] e não encontrei nenhum comentário para ajudar a explicá-lo". Basicamente, tente mostrar que você se esforçou para entendê-lo e explique por que ambos poderiam se beneficiar com a presença de comentários.

Provavelmente 90% do código bem escrito não precisa de comentários. Você realmente deseja apenas documentar as partes do código que foram otimizadas e se tornaram bastante tensas. Eu trabalhei em uma empresa uma vez que exigia que você documentasse todos os trechos de código que você modificou basicamente, os comentários acabaram sendo prejudiciais à legibilidade do código, porque eles geralmente se referiam a códigos que foram removidos ou modificados além do reconhecimento. Cuidado com comentários ruins. Passei uma semana depurando uma função e, no final, descobri que o comentário que eu continuava lendo sobre definir tal e tal sinalizador como "falso" era na verdade toda a questão em que eu defini o sinalizador como "verdadeiro" e tudo funcionou como deveria.


11
Código não comentado não é um código bem escrito. Eu digo aos meus desenvolvedores para colocar um comentário no início de cada bloco como regra geral. Ou reescreva o bloco em um método com um nome de auto-documentação. A menos que seu método seja uma instrução if, uma chamada de método e um retorno, você precisa de um comentário.
rica Remer

@richremer Acho que estamos quase de acordo. Eu aponto para o código de auto-documentação com comentários onde as coisas ficam tensas.
Dkippers

0

Se você deseja que os comentários no código entendam por que algo foi escrito, provavelmente (considerando que você é novo) ainda não entende as necessidades da empresa. Tenho certeza de que você conhece toda a sintaxe e pode ler o código, mas, a menos que saiba o propósito de algum código, ficará um pouco perdido.

Uma coisa que vem à mente é a programação em pares. Você diz que seu chefe está impressionado com o seu progresso, então você pode sugerir trabalhar ao lado dele. Isso ajudará vocês dois a longo prazo. Seu chefe terá que explicar coisas que ele considera como certas e você aprenderá mais sobre o negócio.


0

Como outros já mencionaram, isso é bastante comum, mas isso não significa que você apenas precise absorver e seguir em frente. Você não precisa entender tanto o código com a profundidade que pensa, e existem estratégias concretas para tornar o "ponto mais profundo" muito mais raso:

  • Encontre algo no código relacionado à tarefa em questão. Geralmente, o mais fácil de procurar é algo visível ao usuário, como o rótulo do botão na GUI. Anote onde você o encontrou. Este será o seu ponto de ancoragem.
  • Agora pesquise o código a um passo de distância e anote-o. Quem cria o botão? Qual código é chamado quando o botão é clicado?
  • O controle de origem geralmente é útil para encontrar código a um passo de distância. Descubra quando o código que você está vendo foi adicionado ou alterado e veja o que mais foi feito ao mesmo tempo e por quê.
  • Repita até entender o suficiente para fazer a alteração, além de um nível mais profundo para garantir que você não perca nada.
  • Se você ficar preso a qualquer momento, agora você tem uma pergunta muito específica a fazer. Por exemplo, "Não consigo descobrir de onde esse botão é instanciado".

0

Aqui estão os meus US $ 0,02 sobre o assunto. Não estou sugerindo uma resposta exclusiva, muito do que foi dito aqui é bastante relevante.

Eu tentaria um pouco de engenharia social para organizar as coisas, para que seu chefe achasse mais fácil / menos demorado comentar um pouco do código dele.

Agora, isso pode ser bem fácil se você estiver disposto a correr um grande risco e incomodá-lo - mas não queremos fazer isso. (observação: você pode deixar de fazer qualquer coisa sem que ele escreva ou dite comentários para você, você o insiste e o incomoda infinitamente etc.)

Qual é a alternativa então? Algumas idéias, dependendo da circunstância.

Opção 1

  1. Reserve um tempo para entender um pedaço do código dele como X.
  2. Agora pense em uma maneira razoável de Y interpretar mal .
  3. Diga ao chefe (por e-mail ou diga durante o café da manhã ou o que não estiver) que você está tentando descobrir no momento.
  4. Adicione um comentário dizendo que não está claro o que o código significa, mas você o entende como Y; tente tornar esse comentário visível para ele - mas não tente demais!
  5. Aja assumindo Y - e certifique - se de que seu chefe perceba sua ação (para não perder seu tempo trabalhando muito tempo com uma falsa suposição).
  6. Chefe deve tomar a iniciativa de corrigi-lo. Nesse momento, diga a ele algo como "Eu realmente gostaria que este código tivesse alguns comentários para me impedir de fazer uma suposição errada. Corrigirei o comentário que adicionei por mim mesmo. Você acha que poderia me ajudar com alguma descrição geral?" deste e daquele pedaço de código? Não tenho experiência suficiente para descobrir a intenção exata, e apenas algumas frases fariam o truque. " Ou alguma coisa..

opção 2

Você está treinando. Tente organizar uma reunião semanal de frequência fixa (adicional?) Com ele. Nesta reunião, revise alguns códigos - mas você precisa estar preparado o suficiente para que ele não precise explicar todas as linhas. Em algum momento - espero - ele perceberá que pode pular a reunião se acabou de adicionar os comentários.

Opção 3

Peça a outro colega para não entender o mesmo pedaço de código que você. Vocês abordam o chefe em momentos diferentes, fazendo as mesmas perguntas. Essa é uma maneira infalível de fazê-lo perceber que está falhando em fazer algo ... mas nem todo mundo tem o luxo de colegas de trabalho úteis no mesmo projeto.


0

Então, apenas algo que vai me ajudar até eu entender as coisas, como posso pedir ao meu chefe para colocar comentários em seu código que ele me dá, mas educadamente?

Se você não consegue entender o código, por que você acha que os comentários são a sua solução?

Não conheço o estilo de programação dele, mas admito que, se o nome das funções e variáveis ​​for enganoso, isso dificulta muito a compreensão de um código. Mas se os nomes e funções ou mesmo a organização do programa (classes, métodos, propriedades ...) são para tornar o código compreensível, o código realmente fala com você sozinho.

É melhor pedir a ele a arquitetura do programa e, se você quiser solicitar alguma coisa, peça alguns nomes mais significativos para as funções; isso é mais conveniente para ele fazer.


0

Mesmo se houver uma maneira de perguntar isso educadamente, há duas possibilidades sobre o que seu chefe pensará sobre os comentários em seu código:

  1. Ou que os comentários em seu código seriam uma boa coisa, ou

  2. Que os comentários em seu código não seriam bons.

Se o seu chefe achar que os comentários em seu código não seriam algo bom (e existem argumentos muito bons para isso, ou seja, o código deve ser a documentação , e nenhuma documentação jamais estipulará algo de forma tão precisa e inequívoca) como o código que realmente faz isso ), nada acontecerá.

Agora, se por acaso seu chefe achar que os comentários em seu código seriam uma boa coisa, então há uma chance considerável de que ele o instrua a estudar seu código, entender como ele funciona e continuar a adicionar comentários a ele. codifique- se . (Existem argumentos muito bons para isso também, ou seja, você precisa aprender , e o tempo dele é, por definição, muito mais valioso que o seu .)

Portanto, a menos que você esteja preparado para fazer isso, é melhor não dizer nada.

Ao utilizar nosso site, você reconhece que leu e compreendeu nossa Política de Cookies e nossa Política de Privacidade.
Licensed under cc by-sa 3.0 with attribution required.