<Dart> Effective Dart: Documentation

이번 시간에는 Efective Dart: Documentation에 대해서 공부해보도록 하겠습니다.

어떻게 하면 효과적으로 Dart를 사용할 수 있을까요?

 

https://dart.dev/guides/language/effective-dart/documentation

Effective Dart: Documentation

본 포스트는 공식 문서의 내용을 중심으로 필자의 해석이 주를 이루고 있습니다!

 

글을 작성할때마다 무언가 어투가 바뀌는 거 같아요. 

제가 정신이 없는 점 양해부탁드리면서 시작하도록 하겠습니다.

위 링크를 타고 들어가시면 가장 먼저 

It’s easy to think your code is obvious today without realizing how much you rely on context already in your head. People new to your code, and even your forgetful future self won’t have that context. A concise, accurate comment only takes a few seconds to write but can save one of those people hours of time.

라고 합니다. 살짝 독해를 해보면 오늘날 우리 코드가 명확하다고 생각하기 쉽다고 하네요. 얼마나 우리가 우리 머리 속에서 미리 문법에 대해 의존하는 지를 깨닫는 것 없이. 그러니까 정확한 기준 없이 우리가 짠 코드가 명확하다고 생각한다고 하는 거 같아요. 

또 사람들은 우리의 코드가 처음이고 심지어 우리마저 나중에 그 문법, 그러니까 그 코드를 까먹을 수 있다. 그래서 간결하고 정확한 뭐, 댓글 같은 comment가 (쓰는데 몇초밖에 걸리지 않는) 그런 사람들의 시간을 절약할 수 있다고 하네요,

그러니까 이 말을 바꿔서 하면 comment를 써라!!! 겠죠? >.<

We all know code should be self-documenting and not all comments are helpful. But the reality is that most of us don’t write as many comments as we should. It’s like exercise: you technically can do too much, but it’s a lot more likely that you’re doing too little. Try to step it up.

자, 간단하게 말해서 self-documenting, comment 둘 다 알아야하고 아, 물론 모든 comment가 도움을 주지는 않는다고 해요. 하지만 comment를 많은 사람들이 할 수 있으면서 하지 않는다고 해요. 그리고 comment를 다는 걸 운동 같다고 해요. 기술적으로 많이 할 수 있지만 조금만 한다고, 이 부분을 좀 개발시켜줘라. 라고 하는 거 같아요.

 

자, 그럼 Dart 공식 문서, 그러니까 구글에서 원하는 Comments 는 대체 뭘까요?

Comments

The following tips apply to comments that you don’t want included in the generated documentation.

다음 팁들을 우리가 생성된 문서에 포함시키려고 하지 않는 comments에 적용시켜보라고 하네요.

음.. 그러니까 문서가 생성되고 우리는 보통 comments 즉, 주석을 잘 안달려고 하니까 주석을 달 때 아래와 같은 팁들을 적용시켜보라는 거 같아요.

사실 저도 Comments를 잘 사용하지 않거든요.. 그리고 시간이 지나고 제가 작성한 코드를 보면 이해가 안가서 많은 시간을 쓴 경험이 있어요. 

앞으로 Comments 를 작성하는 노력을 해야할 거 같아요! 저를 위해서!

 

2023/03/06