-
Notifications
You must be signed in to change notification settings - Fork 0
/
md_2015_08_17.html
289 lines (285 loc) · 17.6 KB
/
md_2015_08_17.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="es" xml:lang="es">
<head>
<meta charset="utf-8" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>10 consejos para escribir comentarios en Java - prLázarus</title>
<meta name='Language' content='es' />
<meta name='Content-Language' content='es' />
<meta name="author" content="Carlos J. Peláez Rivas" />
<meta name="description" content="prLázarus - Blog de programación y diario de desarrollo" />
<meta name="keywords" content="lazarus,surazal,prlazarus,blog,programacion,coding,code,desarrollo,development,software,engineer,java,carlos,pelaez,cjpelaez,cjpelaezrivas,malaga,spain" />
<meta property="og:site_name" content="prLázarus" />
<meta property="og:title" content="prLázarus - Blog de programación" />
<meta property="og:description" content="prLázarus - Blog de programación y diario de desarrollo" />
<meta name="twitter:title" content="prLázarus - Blog de programación">
<meta name="twitter:description" content="prLázarus - Blog de programación y diario de desarrollo" />
<link rel="icon" type="image/x-icon" href="media/images/favicon.ico" />
<link rel="shortcut icon" type="image/x-icon" href="media/images/favicon.ico" />
<link rel="canonical" href="https://prlazarus.es/md_2015_08_17">
<link rel="stylesheet" href="static/lib/bootstrap-4.1.3/css/bootstrap.min.css">
<link rel="stylesheet" type="text/css" href="static/lib/fontawesome-4.7/css/fontawesome.min.css" />
<link rel="stylesheet" type="text/css" href="static/lib/hint-2.5.1/css/hint.base.min.css" />
<link rel="stylesheet" type="text/css" href="static/lib/lightbox-2.10/css/lightbox.min.css" />
<link rel="stylesheet" type="text/css" href="static/lib/cookieconsent2-3.1.0/css/cookieconsent.min.css" />
<link rel="stylesheet" type="text/css" href="static/css/base.css" />
<link rel="stylesheet" type="text/css" href="static/css/main.css" />
<link rel="stylesheet" type="text/css" href="static/css/entry.css" />
<link rel="stylesheet" type="text/css" href="static/css/project.css" />
<link rel="stylesheet" type="text/css" href="static/css/toc.css" />
<link rel="stylesheet" type="text/css" href="static/css/code.css" />
<link rel="stylesheet" type="text/css" href="static/css/code-github.min.css" />
<link rel="stylesheet" type="text/css" href="static/css/print.css" media="print" />
<script src="static/lib/jquery-3.3.1/js/jquery.min.js"></script>
<script src="static/lib/bootstrap-4.1.3/js/bootstrap.bundle.min.js"></script>
<script src="static/lib/stickytabs-1.2.0/js/stickytabs.js"></script>
<script src="static/lib/scrolltotop-1.0/js/scrolltotop.js"></script>
<script src="static/lib/lightbox-2.10/js/lightbox.min.js"></script>
<script>
lightbox.option({
'albumLabel': "Imagen %1 de %2",
'fadeDuration': 250,
'resizeDuration': 250,
'wrapAround': true,
'disable': true
})
</script>
<script src="lib/cookieconsent2-3.1.0/js/cookieconsent.min.js"></script>
<script>
window.addEventListener("load", function() {
window.cookieconsent.initialise({
"palette": {
"popup": {
"background": "#d4d4d4",
"text": "#151515"
},
"button": {
"background": "#003379",
"text": "#ffffff"
}
},
"content": {
"message": "Este sitio web utiliza cookies propias y de terceros para que tengas la mejor experiencia de usuario posible. Si continuas navegando estás aceptando el uso de las mencionadas cookies y la política de cookies.",
"dismiss": "Cerrar mensaje",
"link": "Más información",
"href": "https://prlazarus.es/md_cookies_policy.html"
}
})
});
</script>
<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-PWTT0T2YZ0"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag() {
dataLayer.push(arguments);
}
gtag('js', new Date());
gtag('config', 'G-PWTT0T2YZ0');
</script>
</head>
<body>
<div class="container-fluid main-container">
<link rel="stylesheet" type="text/css" href="static/css/navbar.css" />
<div id="navbar">
<div id="zoneA">
<div class="content">
<a href="./">
<div id="logo"></div>
</a>
<h1 id="title">
prLázarus
</h1>
<h2 id="subtitle">
Blog sobre el desarrollo de proyectos, ingeniería software y tutoriales
</h2>
</div>
</div>
<div id="zoneB">
<div class="content">
<div id="menu">
<a class="menuItem" href="./"><i class="fa fa-home"></i><span class="text"> Página principal</span></a>
<a class="menuItem" href="./md_projects.html"><i class="fa fa-rocket"></i><span class="text"> Proyectos</span></a>
<a class="menuItem" href="https://cjpelaezrivas.dev"><i class="fa fa-user-circle"></i><span class="text"> Sobre mí</span></a>
</div>
</div>
</div>
</div>
<div class="fluid-row" id="header">
<h1 class="title toc-ignore ">10 consejos para escribir comentarios en Java</h1>
<div class="date"><em>lunes, 17 de agosto de 2015</em></div>
<div id="entry_section">
<div id="time_section"><b>Tiempo de lectura:</b> 3 minutos</div>
</div>
<div id="tag_section">
<b>Etiquetas: </b>
<a class="tag" href="md_search.html?tag=Consejos">Consejos</a>
<a class="tag" href="md_search.html?tag=Diseño">Diseño</a>
<a class="tag" href="md_search.html?tag=Java">Java</a>
</div>
</div>
<div class="section">
<p>Muy buenas, <br>
Los comentarios son una parte muy importante a la hora de escribir código, no solo en Java, la verdad es que no importa el lenguaje que estés usando. De la mismo forma, es uno de los recursos que se abusa más. Tanto escribir pocos comentarios como muchos es malo, y ha sido remarcado por algunas celebridades como el autor del libro <em>Clean code (Código limpio)</em>, Robert C. Martin. En este libro, el cual tengo pendiente de terminar en estos momentos, hay un capítulo completo dedicado a cómo escribir comentarios, y detalla los pros y contras de estos.</p>
<p>Pero antes de seguir con estos consejos y reglas, vamos a ver cual es el proposito de los comentarios en el código, ¿por qué necesitamos los comentarios? ¿acaso escribir el código no es suficiente? Algunos programadores incluso llegan a decir que a ellos se les paga por escribir código y no comentarios.</p>
<p>En cualquier caso, todos podemos estar de acuerdo en que la mayor parte del tiempo empleado en el desarrollo de un Software se dedica al mantenimiento, y únicamente una pequeña parte se dedica al desarrollo en si. Es en la parte en la que más tiempo se pasa, en el mantenimiento, donde serán necesarios los comentarios.</p>
<p>La mayoría de los programadores no está durante todo el tiempo de vida de un producto Software trabajando en él, y a veces hay gente nueva, la cual debe trabajar con código ya escrito. Esas personas que leen el código y no se interesan por la razón porla cual cierta línea de código está ahí, son a las que les pueden ser útil los comentarios para entender rápido el código.</p>
<p>Vamos a dejar ya las historias y comencemos con una serie de buenas prácticas que todos deberíamos seguir a la hora de escribir comentarios en el código:</p>
<ol>
<li>
<p>Centrate en la legibilidad del código, asume que no existen los comentarios para poder explicar el código. <strong>Dales a los métodos, variables y clases nombres con significado</strong>.</p>
</li>
<li>
<p><strong>No escribas lo que hace el código.</strong> Esta tarea debería ser relegada al código, y debería ser resuelta de manera sencilla siguiente el consejo anterior.</p>
</li>
<li>
<p><strong>Escribe siempre porqué estás escribiendo ese trozo de código.</strong> La razón de escribir ese trozo de código no es visible hasta que lo escribes en los comentarios, y puede llegar a ser crítico para identificar cualquier bug o comportamiento extraño.</p>
</li>
<li>
<p>Si estás escribiendo librerías "core", es decir, que van a ser usadas por varios proyectos y equipos, <strong>sigue siempre el estilo para los comentarios indicados por javadoc</strong>. Documenta además todas las suposiciones y precondiciones para usar tu API.</p>
</li>
<li>
<p><strong>Incluye el id de incidencia y descripciones en los comentarios</strong>, especialmente si estás modificando un trozo de código como parte de un mantenimiento. Esto es realmente útil a la hora de comprarar diferentes versiones de un mismo código. Esto te da ideas claras de porqué ese código en particular ha sido añadido y/o modificado y si el problema viene de ese trozo de código o no.</p>
</li>
<li>
<p>Intenta siempre escribir los comentarios con <strong>el mínimo de palabras posibles</strong>. A nadie le gusta, ni tiene tiempo, de leer comentarios largos.</p>
</li>
<li>
<p><strong>No incluyas en los comentarios historias como tu nombre, id de empleado, departamento, etc.</strong> toda esa información puede ser obtenida, si fuese necesaria, desde los commits realizados y los partes de incidencias durante la fase de mantenimiento.</p>
</li>
<li>
<p><strong>Escribe siempre comentarios a la hora de hacer commit en el repositorio</strong> y en especial el motivo de las modificaciones realizadas. Incluye si es posible en número de incidencia para poder realizar la consulta con más detalle en caso de ser necesario.</p>
</li>
<li>
<p>Si quieres que los desarrolladores venideros sigan ciertos estándares o informar sobre ciertos detalles, entonces será mejor que los <strong>incluyas al principio de tus clases como comentarios</strong>.</p>
</li>
<li>
<p>Por último, pero no menos importante, intenta pasar código a compañeros para que lo lean como parte de la fase de revisión, y ver cuánto son capaces de entender.</p>
</li>
</ol>
<p>Eso es todo por ahora sobre consejos a la hora de crear comentarios que intento usar siempre. Intentar compartir estos conocimientos, y usar las prácticas que mejor os parezcan para escribir buenos comentarios. Creo que esta es una de las areas en las que los programadores nóveles puedes mejorar más (y los más experimentados también).</p>
<p>Saludos, <br>
Lázarus Surazal.
</p>
</div>
<link rel="stylesheet" type="text/css" href="static/css/relations.css" />
<div id="relationsContainer">
<span class="relatedTitle">Entradas relacionadas</span>
<ul>
<li><a href="md_2014_10_01.html">Cómo evitar las NullPointerException (NPE) en Java [Parte 1]</a></li>
<li><a href="md_2015_01_12.html">Cómo evitar las NullPointerException (NPE) en Java [Parte 2]</a></li>
<li><a href="md_2015_08_10.html">Principios de diseño orientado a objetos que todo programador de Java debería conocer</a></li>
<li><a href="md_2018_05_04.html">Contraseñas para nuestro día a día</a></li>
</ul>
</div>
<link rel="stylesheet" type="text/css" href="static/css/navigation.css" />
<hr>
<div id="navigationContainer">
<a class="item hint--bottom-left navigateButton right" href="md_2015_08_24.html" data-hint="Hilo (Thread) con eventos [Java]">
Siguiente
<i class="fa fa-arrow-right"></i>
</a>
<a class="item hint--bottom-right navigateButton left" href="md_2015_08_10.html" data-hint="Principios de diseño orientado a objetos que todo programador de Java debería conocer">
<i class="fa fa-arrow-left"></i>
Anterior
</a>
<a class="navigateButton center" href="./">
<i class="fa fa-home"></i>
Volver a la página principal
</a>
</div>
<link rel="stylesheet" type="text/css" href="static/css/info.css" />
<div id="infoContainer">
<div id="infoProfile" class="info_block">
<div class="title">
<b>Perfil</b>
</div>
<div class="content">
<div class="part photo">
<img src="media/images/logo_b.png" width="90px" alt="prLázarus logo info" />
</div>
<div class="part description">
<h3 id="name">Carlos J. Peláez Rivas <em id="alias">(Lázarus Surazal)</em></h3>
Graduado y Máster en Ingeniería Informática por la Universidad de Málaga (España). También cursé un Experto en tecnologías de Blockchain. Actualmente trabajando como Software engineer en Málaga.<br>
Apasionado de los videojuegos, la música y la tecnología; siempre buscando cosas nuevas que aprender, hacer (y a veces romper).<br>
<a href="https://cjpelaezrivas.dev">Más sobre mi...</a>
</div>
</div>
</div>
<div id="infoContact" class="info_block">
<div class="title">
<b>Contacto</b>
</div>
<div class="content links">
<div class="item hint--bottom-right" data-hint="Perfil personal">
<a href="https://cjpelaezrivas.dev" style="font-size: 38px; line-height: 38px;"><i class="fa fa-user-circle"></i></a>
</div>
<div class="item hint--bottom-right" data-hint="prLázarus - RSS">
<a href="./feed.xml"><i class="fa fa-rss-square"></i></a>
</div>
<div class="item hint--bottom-right" data-hint="Enviar correo electrónico">
<a href="mailto:prlazarus.info@gmail.com"><i class="fa fa-envelope-square"></i></a>
</div>
<div class="item hint--bottom-right" data-hint="Perfil de GitHub">
<a href="https://github.com/cjpelaezrivas"><i class="fa fa-github-square"></i></a>
</div>
<div class="item hint--bottom-right" data-hint="Perfil de LinkedIn">
<a href="https://www.linkedin.com/in/cjpelaezrivas"><i class="fa fa-linkedin-square"></i></a>
</div>
</div>
</div>
</div>
<div id="commentsContainer" style="float:left; width:100%;">
<script src="https://utteranc.es/client.js" repo="cjpelaezrivas/prlazarus" issue-term="title" label="comments" theme="github-light" crossorigin="anonymous" async>
</script>
<noscript>
<div class="block warning icon fa-exclamation" style="margin-bottom:20px;">
Por favor, activa JavaScript para ver los comentarios.
</div>
</noscript>
</div>
<link rel="stylesheet" type="text/css" href="static/css/footer.css" />
<div id="footer_message">
¿Has encontrado algún error? <a href="mailto:prlazarus.info@gmail.com">Envía un correo electrónico</a> o <a href="https://github.com/cjpelaezrivas/prLazarus/issues">abre un nuevo <i>issue</i></a> para corregirlo. Gracias.
</div>
<div id="footer">
<div class="content">
<div id="logo_footer">
<a href="https://prlazarus.es"><img src="media/images/logo_c.png" alt="prLázarus logo footer" style="margin-top:10px;" /></a>
<!-- <span class="text" style="display:block; text-align:center; margin-top:-4px;">© 2012 - 2018</span> -->
</div>
<div id="right_column" class="text">
Escrito desde <a href="https://es.wikipedia.org/wiki/Espa%C3%B1a"><img src="media/images/spain.png" style="margin: -2px 2px 0 2px;" alt="Spain flag" /></a> con <i class="fa fa-heart" style="color:#cc0000"></i> por un humano (no IA) <i class="fa fa-child" style="font-size:18px"></i><br>
<i class="fa fa-plug"></i> Con la tecnología de <i><a href="https://cjpelaezrivas.dev/Lighthouse/">Lighthouse</a></i> y <i><a href="https://pages.github.com/">GitHub Pages</a></i><br>
<i><a href="./feed.xml">RSS</a></i>
|
<i><a href="md_cookies_policy.html">Política de cookies</a></i>
|
<i><a href="md_disclaimer.html">Limitación de responsabilidad</a></i><br>
<a href="mailto:prlazarus.info@gmail.com">prlazarus.info@gmail.com</a>
</div>
</div>
</div>
<link rel="stylesheet" type="text/css" href="static/css/progressBar.css" />
<div id="progressBarContainer">
<div class="progressBar">
</div>
</div>
<script src="js/progressBar.js"></script>
</div>
<!-- Default Statcounter code for prLázarus - Blog -->
<script type="text/javascript">
var sc_project = 12995152;
var sc_invisible = 1;
var sc_security = "7de2ea10";
</script>
<script type="text/javascript" src="https://www.statcounter.com/counter/counter.js" async></script>
<noscript>
<div class="statcounter">
<a title="Web Analytics" href="https://statcounter.com/" target="_blank"><img class="statcounter" src="https://c.statcounter.com/12995152/0/7de2ea10/1/" alt="Web Analytics" referrerPolicy="no-referrer-when-downgrade"></a>
</div>
</noscript>
<!-- End of Statcounter Code -->
</body>
</html>