Có phải là bình thường / chấp nhận được để viết ra ghi chú, suy nghĩ, thuật toán, quyết định trong quá trình mã hóa và bảo trì? [đóng cửa]


22

Một số người có vấn đề này mà họ không thể nghĩ mà không có lời. Và viết ra những suy nghĩ và quyết định của họ là cách hiệu quả nhất để tiến hành.

Vì vậy - có bình thường và chấp nhận được không khi tôi viết ra những suy nghĩ và quyết định của mình trong một số tệp Notepad ++ trong quá trình mã hóa?

Đôi khi nó phải được chấp nhận, ví dụ như khi tạo lại tài liệu kỹ thuật hoặc lý luận về các thuật toán phức tạp hơn, nhưng đôi khi nó có thể lạ, ví dụ như khi tôi đang xem xét các lựa chọn thiết kế và cố gắng đưa ra phán đoán.

Tác động của thực hành này đến năng suất là không rõ ràng. Từ một phía - lý luận với các từ bên trong có thể nhanh hơn so với các từ viết. Từ phía khác - vấn đề phức tạp hơn đòi hỏi phải viết. Bên cạnh đó, nếu một người bị mắc kẹt với nhiều lựa chọn thiết kế hơn, thì cảm giác sẽ tốt hơn khi quyết định được viết ra, vì vậy nó làm tăng tinh thần.


5
Tôi có xu hướng làm điều này là tốt, và nói chung là hối tiếc khi tôi không. Thật sự hữu ích khi có một cái gì đó để nhìn lại sau này để nhớ tại sao bạn lại làm một điều gì đó theo cách nào đó hoặc để có thể đưa ra quyết định sau đó khi bạn không khuỷu tay sâu trong đó với tầm nhìn đường hầm. Khi tôi quên ghi chú một cái gì đó, tôi thường quên tại sao, và sau đó dành nhiều thời gian hơn để kiểm tra lại các bước của tôi.
PseudoPsyche

21
Tôi cảm thấy như chúng ta đang thiếu một phần của bối cảnh? Là quan sát này được thực hiện xung quanh một khiếu nại xung quanh hiệu quả? Thông thường, những lời chỉ trích đi kèm với gợi ý cho nguyên nhân gốc rễ có thể có hoặc không có liên quan.
Jim Rush

9
"Nhận xét và tài liệu" cần được ghi lại vào mã nguồn và lưu giữ. Suy nghĩ của bạn về việc xem xét các lựa chọn thiết kế có thể được viết ra, nhưng thường không được lưu giữ, đó là thứ sẽ hiếm khi giúp bạn sau này (bạn có thể ghi chú về kết quả của quá trình suy nghĩ đó, nếu nó không rõ ràng từ chính mã nguồn, nhưng đó không phải là những gì bạn hỏi về). Nếu bạn thích một hình thức điện tử, một hình thức bút chì và giấy, hoặc nếu bạn có thể làm tất cả điều này trong đầu, tùy thuộc vào bạn, không ai khác ngoài bạn có thể cho bạn biết những gì phù hợp nhất với bạn.
Doc Brown

4
... PS: Tôi thường thích bút chì và giấy, hoặc bảng trắng cho những thứ này và tôi nghĩ rằng tôi sẽ không trở thành một lập trình viên tốt hơn nếu tôi cố gắng làm tất cả những điều này trong đầu, hoàn toàn ngược lại.
Doc Brown

7
Tại sao nó không được chấp nhận? Chấp nhận cho ai?
Paul D. Chờ

Câu trả lời:


62

Không chỉ là bình thường, đó là một ý tưởng tốt.

Có một câu nói nổi tiếng

"Hãy cho tôi sáu giờ để chặt cây và tôi sẽ dành bốn cái đầu tiên để mài rìu".

Dành thời gian để sắp xếp suy nghĩ của bạn và lập kế hoạch cho công việc của bạn trước khi mã hóa là thời gian tốt. Đặt những suy nghĩ đó lên giấy sẽ cho bạn thời gian để suy nghĩ về kế hoạch của mình, phê bình chúng và sắp xếp chúng theo những cách sẽ rất khó khăn nếu chỉ thực hiện "trong đầu bạn".


8
Đó là một trích dẫn hay, mặc dù tôi đã loại bỏ sự quy kết sai lầm. quoteinvestigator.com/tag/abraham-lincoln
Paul Draper

1
Chắc chắn là một tuyên bố đúng và trích dẫn tốt, nhưng theo hiểu biết của tôi câu hỏi có một trọng tâm khác. Theo tôi hiểu, OP không nghi ngờ gì về tầm quan trọng của việc lên kế hoạch trước. Anh ấy hỏi liệu có hiệu quả hơn khi viết những suy nghĩ / lập kế hoạch này không, hay chỉ để giữ tất cả chúng trong đầu.
Doc Brown

2
Reckon một giờ mài là quá đủ. Nhiệm vụ này đáng lẽ phải được ước tính ở mức tối đa 3 giờ, nhưng sự chậm chạp đã được dành cho việc chuẩn bị quá mức vô nghĩa. Đạo đức một lần nữa là gì? ;-)
Steve Jessop

26

Vâng, điều này là hoàn toàn chấp nhận được và bình thường.

Tài liệu về quá trình ra quyết định của bạn thường có giá trị khi xem lại mã, để giúp xác định lý do tại sao mã được viết theo một cách nhất định.

Các ghi chú này có thể được bao gồm trực tiếp trong mã dưới dạng nhận xét, nếu đủ ngắn. Bình luận mở rộng thường được lưu giữ như một phần của tài liệu thiết kế kỹ thuật bên ngoài.


4
Tôi đặc biệt khuyên bạn không nên bao gồm các ghi chú về việc xem xét các tùy chọn thiết kế và cố gắng đưa ra đánh giá như nhận xét trong mã nguồn, những điều này không bao giờ là "đủ ngắn". Chỉ có kết quả cuối cùng của quá trình suy nghĩ đó, nhưng điều đó hoàn toàn khác với những gì OP đã yêu cầu.
Doc Brown

3
Tôi thường thấy mình trong các cuộc thảo luận dọc theo dòng chữ "tại sao chúng ta lại đưa ra quyết định này". Thật hữu ích khi quay lại các ghi chú dự án hàng ngày của tôi để cung cấp ngữ cảnh, bao gồm cả các lựa chọn thay thế mà chúng ta đã thảo luận. Tôi nghĩ rằng tôi đang ở trong một công ty tốt: theo Cửa hàng Mọi thứ Jeff Bezos cũng làm như vậy.
kdgregory

8
@DocBrown - đôi khi nó là một ý tưởng tốt để bao gồm lý do tại sao bạn không sử dụng có thể phương pháp / thuật toán khác do đó, một nhà phát triển trong tương lai sẽ không cố gắng để thay thế những gì bạn đã làm
HorusKol

1
@HorusKol: chắc chắn, trong một số trường hợp hiếm hoi, đó là lẽ thường tình tầm thường. Nhưng điều đó hoàn toàn khác với "ghi lại quá trình ra quyết định" .
Doc Brown

1
@DocBrown đúng, tôi không nghĩ có ai muốn các trang ghi chú trong mã nguồn của họ. :)
mcknz

20

Đó là một ý tưởng tốt chết tiệt. Phải cho đến khi nó trở thành một cách để trì hoãn.

Chìa khóa là sự cân bằng. Tôi thấy tôi làm việc hiệu quả nhất nếu tôi không tự nhốt mình nhưng nắm bắt ý tưởng khi chúng đến.

Nếu tôi đang nghiền ở cấp độ thấp và một ý tưởng cấp cao xuất hiện, tôi chỉ cần ghi lại và quay lại với nó sau.

Lên kế hoạch cho công việc là một ý tưởng tốt nhưng trừ khi bạn phải giao tiếp hoặc trình bày trước khán giả, công cụ tốt nhất là bút và khăn ăn. Nắm bắt ý tưởng. Đừng lãng phí thời gian để làm cho nó đẹp.


Markdown là một cách tuyệt vời khác để ghi chú lại. Giữ bàn tay của bạn trên bàn phím, do đó, có sự gián đoạn tối thiểu cho quá trình suy nghĩ.
RubberDuck

1
Cho dù bắn một biên tập viên hay lấy bút và khăn ăn là cách thay thế tốt hơn hoàn toàn phụ thuộc vào kỹ năng đánh máy và viết tay của bạn. Đối với tôi, giải pháp tốt hơn rõ ràng là biên tập viên.
cmaster

9

Trong mọi tình huống chuyên nghiệp, nó không chỉ "bình thường và chấp nhận được", nó là bắt buộc. Chu trình phát triển điển hình bao gồm hai giai đoạn tài liệu trước khi bất kỳ mã hóa nào bắt đầu:

  1. Tài liệu yêu cầu chức năng: thường được viết bởi các nhà phân tích kinh doanh, chỉ định chức năng sẽ được thực hiện.

  2. Tài liệu thiết kế chi tiết: gần như những gì bạn đang nói, chính thức hơn, chỉ định phân rã chức năng (bao thanh toán) của hệ thống, thuật toán, v.v. Một số (rất) cũ của tôi đang trực tuyến, ví dụ như điều này .

Đối với tài liệu ít chính thức hơn, tôi 110% đồng ý với các nhận xét trước về nhận xét nội tuyến. Đó là cách duy nhất để đi; Bằng cách này hay cách khác, mọi thứ khác cuối cùng bị mất. Nhưng bình luận nội tuyến gọn gàng và chu đáo là một kỹ năng mã hóa riêng biệt, được phát triển thông qua nỗ lực và thực hành như bất kỳ kỹ năng nào khác. Bạn có thể thấy một số thứ (rất) cũ của tôi tại, ví dụ như cái này . Phong cách đó có thể hoặc không thể hấp dẫn bạn. Trước tiên tôi khuyên bạn nên tìm một số mã được nhận xét tốt với kiểu bạn thích và mô phỏng mã đó theo mã của riêng bạn. Sau một thời gian, điều chỉnh nó khi bạn thấy phù hợp.


4

Một nơi tuyệt vời để đưa loại thông tin này trực tiếp vào thông điệp cam kết của hệ thống kiểm soát phiên bản của bạn (SVN, git, v.v.). Bằng cách này bạn có thể thấy những thay đổi và lý do cho chúng ở cùng một nơi.


1
Nó cũng làm cho họ có thể tìm kiếm. Bạn có thể tìm kiếm các thông điệp cam kết trong dòng lệnh git và sourcetree, v.v.
Hy vọng có ích vào

Tôi cố gắng thực hiện điều này trong cả tuyên bố cam kết cũng như yêu cầu lỗi hoặc tính năng có liên kết đến cam kết. Tôi cũng thực hiện các nhận xét nội tuyến trong mã với lý do tại sao tôi thay đổi mã. Điều này giúp đáng kể trong cơ sở mã cũ khó hiểu của chúng tôi, nơi các ý kiến ​​chủ yếu là không rõ.
delliottg 27/8/2016

Không, đây là một cái gì đó khác. Thông điệp cam kết nên mô tả những gì đã được thực hiện, không phải tại sao. Tại sao đi vào nhận xét mã tài liệu của bạn, tài liệu đi kèm và giải quyết vấn đề theo dõi. Bạn không thể đặt năm trang ghi chú và thiết kế công việc trong một thông điệp cam kết, bạn cũng không nên muốn.
Cuộc đua nhẹ nhàng với Monica

Thật tuyệt khi đặt nó trong hệ thống kiểm soát phiên bản. Một nơi tốt hơn là một tập tin văn bản đơn giản bên trong mặc dù. Những người dễ sử dụng hơn tin nhắn cam kết.
Thorbjørn Ravn Andersen

2

Ngoài những câu trả lời hay khác, tôi sẽ nói thêm rằng tôi thường viết ra những suy nghĩ của mình về những gì tôi đang cố gắng làm.

Rất rõ ràng về việc nói rõ những gì tôi đang cố gắng giúp tôi nhận ra các giả định, giả định và / hoặc các yêu cầu không nhất thiết phải giữ.

Điều đó sau đó gợi ý về các lựa chọn thay thế, mà sau đó tôi có thể nghiền ngẫm tốt hơn từng lượt; văn bản đó giúp tiết kiệm vị trí của tôi nếu tôi nghĩ về điều gì khác.

Tôi ghi chú nhanh để khám phá hơi thở và độ sâu, để nó hoạt động đệ quy, giúp tôi xây dựng, điều hướng và đánh giá một cây giải pháp, sao lưu, khám phá, khám phá, nhận ra và quyết định.


1

Viết ra bất cứ điều gì có thể giúp bạn tiết kiệm / (mới) đồng đội là thời gian chi tiêu tốt. Chỉ cần chắc chắn rằng đó là thứ mà ai đó có thể cần sau này và đừng lật đổ trừ khi đó là một dự án dài hạn thực sự.

Nó cũng không nên mất bất cứ lúc nào. Nếu bạn dành thời gian suy nghĩ, bạn có thể viết suy nghĩ của mình xuống 1 đến 1 (miễn là chúng sẽ / có thể hữu ích cho ai đó).

Vấn đề thực sự có thể là lật đổ những gì bạn viết. Chỉ vì bạn đang viết không có nghĩa là bạn phải tuân thủ một số định dạng đã tồn tại hoặc cần phải thực hiện tất cả các cách để tạo một tài liệu đầy đủ.

Nếu sự lựa chọn của bạn là giữa việc không viết ra bất cứ điều gì và chỉ viết ghi chú không chính thức trên một sổ ghi chép, thì chỉ cần viết ghi chú không chính thức.


1

Bạn nói: "Một số người có vấn đề này mà họ không thể nghĩ mà không có lời. Và viết ra những suy nghĩ và quyết định của họ là cách hiệu quả nhất để tiến hành."

Nếu viết ra những suy nghĩ và quyết định của bạn là cách hiệu quả nhất để tiến hành, tại sao nó không bình thường và được chấp nhận để tiến hành theo cách hiệu quả nhất? Bạn làm những gì tốt nhất cho bạn. Nó có thể không phải là những gì làm việc tốt nhất cho người khác. Trong trường hợp đó, bạn không để người khác nói cho bạn điều gì là tốt nhất cho bạn và bạn không nói với họ điều gì là tốt nhất cho họ. Mọi người đều làm những gì tốt nhất cho họ.


1

Con người chỉ có thể giữ khoảng bảy "thứ" trong đầu. Đó là lý do cho số điện thoại bảy chữ số. Để các lập trình viên làm việc hiệu quả, họ phải tìm một số loại hệ thống để giảm tải mọi thứ từ bộ nhớ của họ và nhanh chóng lấy lại nó sau khi cần. Ghi chép của bạn là một cách rõ ràng và trực tiếp, nhưng tất cả mọi người làm việc trên bất cứ điều gì phức tạp vừa phải phải làm điều đó bằng cách nào đó . Khi bạn ghép chương trình với ai đó, hãy tạo một điểm để tìm phương pháp của họ.

Một cách phổ biến là phát triển theo hướng kiểm tra. Trong phương pháp này, bạn viết một thử nghiệm thất bại, bạn viết mã vừa đủ để vượt qua thử nghiệm thất bại đó, sau đó bạn cấu trúc lại mã của mình để làm cho nó trông đẹp hơn trong khi vẫn giữ tất cả các thử nghiệm hiện tại của bạn. Phương pháp này giữ cho tất cả các "ghi chú" của bạn được mã hóa trong các bài kiểm tra. Mọi người có thể làm việc rất nhanh theo cách này mà không cần ghi chú, vì họ chỉ tập trung vào bài kiểm tra tiếp theo.

Một cách phổ biến khác là chỉ viết ghi chú của bạn trong mã của bạn dưới dạng nhận xét mã giả hoặc sơ khai, sau đó dần dần thay thế nó bằng thực tế. Đây là cách tôi thường viết các thuật toán. Bản nháp đầu tiên của tôi chỉ là một chức năng chính với mã giả, sau đó dần dần nó lấp đầy vào mức độ trừu tượng ngày càng sâu hơn.

Đừng cảm thấy tồi tệ khi sử dụng bất kỳ phương pháp nào phù hợp với bạn, nhưng hãy cố gắng chú ý những phương pháp mà các đồng nghiệp "hiệu quả" của bạn đang sử dụng. Họ có những hạn chế giống như con người bạn làm.


1
TDD là một bài tập ghi chú? Tôi không nghĩ vậy.
Robert Harvey
Khi sử dụng trang web của chúng tôi, bạn xác nhận rằng bạn đã đọc và hiểu Chính sách cookieChính sách bảo mật của chúng tôi.
Licensed under cc by-sa 3.0 with attribution required.